semverify 0.3.0

data/lib/semverify/regexp.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Semverify
+  # Match a semver within a string
+  SEMVER_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
+  SEMVER_REGEXP_FULL = /\A#{SEMVER_REGEXP.source}\z/x
+end

data/lib/semverify/semver.rb

@@ -0,0 +1,372 @@
+# frozen_string_literal: true
+
+require 'semverify/regexp'
+
+module Semverify
+  # 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 = Semverify::Semver.new('1.2.3')
+  #   semver.major # => '1'
+  #   semver.minor # => '2'
+  #   semver.patch # => '3'
+  #
+  # @example Parsing a version with a pre-release identifier
+  #   semver = Semverify::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 = Semverify::Semver.new('1.2.3+build.1')
+  #   semver.build_metadata # => 'build.1'
+  #
+  # @example Comparing versions
+  #   semver1 = Semverify::Semver.new('1.2.3')
+  #   semver2 = Semverify::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 Semver
+    include Comparable
+
+    # Create a new Semver object
+    #
+    # @example
+    #   version = Semverify::Semver.new('1.2.3-alpha.1')
+    #
+    # @param version [String] The version string to parse
+    #
+    # @raise [Semverify::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 = Semverify::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 = Semverify::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 = Semverify::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 = Semverify::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 = Semverify::Semver.new('1.2.3-alpha.1+build.001')
+    #   semver.pre_release #=> 'alpha.1'
+    #
+    # @example When the version has no pre_release part
+    #   semver = Semverify::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 = Semverify::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 = Semverify::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 = Semverify::Semver.new('1.2.3-alpha.1+build.001')
+    #   semver.build_metadata #=> 'build.001'
+    #
+    # @example When the version has no build_metadata part
+    #   semver = Semverify::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 = Semverify::Semver.new('1.2.3')
+    #   semver2 = Semverify::Semver.new('1.2.4')
+    #   semver1 <=> semver2 # => -1
+    #   semver2 <=> semver1 # => 1
+    #
+    # @example A Semver is equal to itself
+    #   semver1 = Semverify::Semver.new('1.2.3')
+    #   semver1 <=> semver1 # => 0
+    #
+    # @example A pre-release version is always older than a normal version
+    #   semver1 = Semverify::Semver.new('1.2.3-alpha.1')
+    #   semver2 = Semverify::Semver.new('1.2.3')
+    #   semver1 <=> semver2 # => -1
+    #
+    # @example Pre-releases are compared by the parts of the pre-release version
+    #   semver1 = Semverify::Semver.new('1.2.3-alpha.1')
+    #   semver2 = Semverify::Semver.new('1.2.3-alpha.2')
+    #   semver1 <=> semver2 # => -1
+    #
+    # @example Build metadata is ignored when comparing versions
+    #   semver1 = Semverify::Semver.new('1.2.3+build.100')
+    #   semver2 = Semverify::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 [Semverify::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
+    #   Semverify::Semver.new('1.2.3').valid? # => true
+    #   Semverify::Semver.new('1.2.3-alpha.1+build.001').valid? # => true
+    #   Semverify::Semver.new('bogus').valid? # => raises Semverify::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
+    #   Semverify::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
+    #   Semverify::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(Semverify::SEMVER_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 [Semverify::Error] if other is not a valid Semver
+    # @api private
+    def assert_other_is_a_semver(other)
+      raise Semverify::Error, 'other must be a Semver' unless other.is_a?(Semver)
+    end
+
+    # Raise a error if the given version is not a string
+    # @param version [Semver] the version to check
+    # @return [void]
+    # @raise [Semverify::Error] if the given version is not a string
+    # @api private
+    def assert_version_must_be_a_string(version)
+      raise Semverify::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 [Semverify::Error] if other is not a valid Semver
+    # @api private
+    def assert_valid_version
+      raise Semverify::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

data/lib/semverify/version.rb

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

data/lib/semverify/version_file.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Semverify
+  # Represents a file that contains the gem's version and can update the version
+  #
+  # Use VersionFileFactory.find create a VersionFile instance.
+  #
+  # @api public
+  #
+  class VersionFile
+    # Create an VersionFile instance
+    #
+    # Use VersionFileFactory.find create a VersionFile instance.
+    #
+    # @example
+    #   version_file = Semverify::VersionFile.new('VERSION', 'VERSION = "', '1.2.3', '"')
+    #
+    # @param path [String] the path to the file relative to the current directory
+    # @param content_before [String] the content before the version
+    # @param version [String] the version
+    # @param content_after [String] the content after the version
+    #
+    # @raise [Semverify::Error] if the version is not an IncrementableSemver
+    #
+    # @api private
+    #
+    def initialize(path, content_before, version, content_after)
+      raise Semverify::Error, 'version must be an IncrementableSemver' unless
+        version.is_a?(Semverify::IncrementableSemver)
+
+      @path = path
+      @content_before = content_before
+      @version = version
+      @content_after = content_after
+    end
+
+    # @!attribute [r]
+    #
+    # The path to the file relative to the current directory
+    #
+    # @example
+    #   version_file = Semverify::VersionFile.new('lib/semverify/version.rb', 'VERSION = "', '1.2.3', '"')
+    #   version_file.path # => 'lib/semverify/version.rb'
+    # @return [String]
+    # @api public
+    attr_reader :path
+
+    # @!attribute [r]
+    #
+    # The content in the version file before the version
+    #
+    # @example
+    #   version_file = Semverify::VersionFile.new('lib/semverify/version.rb', 'VERSION = "', '1.2.3', '"')
+    #   version_file.content_before # => 'VERSION = "'
+    # @return [String]
+    # @api public
+    attr_reader :content_before
+
+    # @!attribute [r]
+    #
+    # The version from the version file
+    #
+    # @example
+    #   version = Semverify::IncrementableSemver.new('1.2.3')
+    #   version_file = Semverify::VersionFile.new('lib/semverify/version.rb', 'VERSION = "', version, '"')
+    #   version_file.version.to_s # => '1.2.3'
+    # @return [Semverify::IncrementableSemver]
+    # @raise [Semverify::Error] if the version is not an IncrementableSemver
+    # @api public
+    attr_reader :version
+
+    # @!attribute [r]
+    #
+    # The content in the version file before the version
+    #
+    # @example
+    #   version_file = Semverify::VersionFile.new('lib/semverify/version.rb', 'VERSION = "', '1.2.3', '"')
+    #   version_file.content_after # => '"'
+    # @return [String]
+    # @api public
+    attr_reader :content_after
+
+    # Update the version in the version file
+    #
+    # @param new_version [Semverify::IncrementableSemver] the new version
+    # @example
+    #   version_file = Semverify::VersionFile.new('lib/semverify/version.rb', 'VERSION = "', '1.2.3', '"')
+    #   version_file.version = '1.2.4'
+    # @return [Void]
+    # @raise [Semverify::Error] if new_version is not an IncrementableSemver
+    # @api public
+    #
+    def version=(new_version)
+      raise Semverify::Error, 'new_version must be an IncrementableSemver' unless
+        new_version.is_a?(Semverify::IncrementableSemver)
+
+      @version = version
+      File.write(path, content_before + new_version.to_s + content_after)
+    end
+  end
+end

data/lib/semverify/version_file_factory.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'semverify/version_file_sources'
+
+module Semverify
+  # Finds the file that contains the gem's version and returns a VersionFile instance
+  #
+  # @api public
+  #
+  class VersionFileFactory
+    # The list of VersionFileSources to check for the version file
+    #
+    # The order of the list is important. The first VersionFileSource that finds a version file will be used.
+    #
+    VERSION_FILE_SOURCES = [
+      Semverify::VersionFileSources::Version,
+      Semverify::VersionFileSources::VersionRb,
+      Semverify::VersionFileSources::Gemspec
+    ].freeze
+
+    # Finds the version file for the gem
+    #
+    # @example
+    #   version_file = Semverify::VersionFileFactory.find
+    #   version_file.path # => 'lib/semverify/version.rb'
+    #   version_file.version # => '1.2.3'
+    #
+    # @return [Semverify::VersionFile, nil] the version file or nil if no version file was found
+    #
+    def self.find
+      VERSION_FILE_SOURCES.each do |version_file_source|
+        version_file = version_file_source.find
+        return version_file if version_file
+      end
+      nil
+    end
+  end
+end

data/lib/semverify/version_file_sources/base.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'semverify/version_file'
+
+module Semverify
+  module VersionFileSources
+    # Base class for a version file source which implements #find
+    #
+    # @api public
+    #
+    class Base
+      # The first file from #glob whose content matches #content_regexp
+      #
+      # @example
+      #   version_file = Semverify::VersionFileSources::Gemspec.find
+      #
+      # @return [Semverify::VersionFile, nil] the version file or nil if no version file was found
+      #
+      def self.find
+        Dir[glob].filter_map do |path|
+          if (match = File.read(path).match(content_regexp))
+            version = Semverify::IncrementableSemver.new(match[:version])
+            Semverify::VersionFile.new(path, match[:content_before], version, match[:content_after])
+          end
+        end.first
+      end
+
+      private
+
+      # The version file regexp
+      #
+      # A regular expression that matches the version file and has three named captures:
+      # - content_before: the content before the version
+      # - version: the version
+      # - content_after: the content after the version
+      #
+      # @return [Regexp]
+      # @api private
+      private_class_method def self.content_regexp
+        raise NotImplementedError, 'You must implement #content_regexp in a subclass'
+      end
+
+      # A glob that matches potential version files
+      #
+      # Files matching this glob will be checked to see if they match #version_file_regexp
+      #
+      # @return [String]
+      # @api private
+      private_class_method def self.glob
+        raise NotImplementedError, 'You must implement #glob in a subclass'
+      end
+    end
+  end
+end

data/lib/semverify/version_file_sources/gemspec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'semverify/version_file_sources/base'
+
+module Semverify
+  module VersionFileSources
+    # Checks for the gem's version in a file named *.gemspec
+    #
+    # @api public
+    #
+    class Gemspec < Base
+      # The regexp to find the version and surrounding content within the gemspec
+      VERSION_REGEXP = /
+        \A
+          (?<content_before>
+            .*
+            \.version\s*=\s*(?<quote>['"])
+          )
+          (?<version>#{Semverify::SEMVER_REGEXP.source})
+          (?<content_after>\k<quote>.*)
+        \z
+      /xm
+
+      private
+
+      # The version file regexp
+      # @return [Regexp]
+      # @api private
+      private_class_method def self.content_regexp = VERSION_REGEXP
+
+      # A glob that matches potential version files
+      # @return [String]
+      # @api private
+      private_class_method def self.glob = '*.gemspec'
+    end
+  end
+end

data/lib/semverify/version_file_sources/version.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'semverify/version_file_sources/base'
+
+module Semverify
+  module VersionFileSources
+    # Checks for the gem's version in a file named VERSION
+    #
+    # @api public
+    #
+    class Version < Base
+      # The regexp to find the version and surrounding content within the version file
+      VERSION_REGEXP = /
+        \A
+          (?<content_before>\s*)
+          (?<version>#{Semverify::SEMVER_REGEXP.source})
+          (?<content_after>\s*)
+        \z
+      /x
+
+      private
+
+      # The version file regexp
+      # @return [Regexp]
+      # @api private
+      private_class_method def self.content_regexp = VERSION_REGEXP
+
+      # A glob that matches potential version files
+      # @return [String]
+      # @api private
+      private_class_method def self.glob = 'VERSION'
+    end
+  end
+end