version_gem 1.1.3 → 1.1.9

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -6,8 +6,16 @@
 |----------|-----------|
 | 1.latest | ✅         |
 
-## Reporting a Vulnerability
+## Security contact information
 
-Peter Boling is the primary maintainer of this gem. Please find a way
-to [contact him directly](https://railsbling.com/contact) to report the issue. Include as much relevant information as
-possible.
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+## Additional Support
+
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
+
+[README]: README.md

data/lib/version_gem/api.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module VersionGem
   # Public API of this library
   module Api

data/lib/version_gem/epoch.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "api"
+
+module VersionGem
+  # Support for Epoch Semantic Versioning
+  # See: https://antfu.me/posts/epoch-semver
+  module Epoch
+    EPOCH_SIZE = 1_000
+
+    class << self
+      def extended(base)
+        raise Error, "VERSION must be defined before 'extend #{name}'" unless defined?(base::VERSION)
+
+        base.extend(Api)
+        base.extend(OverloadApiForEpoch)
+      end
+    end
+
+    # Tweak the basic API so it will support Epoch Semantic Versioning
+    module OverloadApiForEpoch
+      # *** OVERLOAD METHODS FROM API ***
+      #
+      # The epoch version
+      #
+      # @return [Integer]
+      def epoch
+        @epoch ||= _major / EPOCH_SIZE
+      end
+
+      # The major version
+      #
+      # @return [Integer]
+      def major
+        @major ||= _major % EPOCH_SIZE
+      end
+
+      # The version number as a hash
+      #
+      # @return [Hash]
+      def to_h
+        @to_h ||= {
+          epoch: epoch,
+          major: major,
+          minor: minor,
+          patch: patch,
+          pre: pre,
+        }
+      end
+
+      # NOTE: This is not the same as _to_a, which returns an array of strings
+      #
+      # The version number as an array of cast values
+      # where epoch and major are derived from a single string:
+      #   EPOCH * 1000 + MAJOR
+      #
+      # @return [Array<[Integer, String, NilClass]>]
+      def to_a
+        @to_a ||= [epoch, major, minor, patch, pre]
+      end
+
+      private
+
+      def _major
+        @_major ||= _to_a[0].to_i
+      end
+    end
+  end
+end

data/lib/version_gem/error.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
 module VersionGem
+  # Errors raised by VersionGem will be of this class
   class Error < RuntimeError; end
 end

data/lib/version_gem/rspec.rb

@@ -12,6 +12,12 @@ RSpec::Matchers.define(:have_version_as_string) do
   end
 end
 
+RSpec::Matchers.define(:have_epoch_as_integer) do
+  match do |version_mod|
+    version_mod.epoch.is_a?(Integer)
+  end
+end
+
 RSpec::Matchers.define(:have_major_as_integer) do
   match do |version_mod|
     version_mod.major.is_a?(Integer)
@@ -52,3 +58,22 @@ RSpec.shared_examples_for("a Version module") do |version_mod|
     end
   end
 end
+
+# This one is more Epoch ;)
+RSpec.shared_examples_for("an Epoch Version module") do |version_mod|
+  it "is introspectable" do
+    aggregate_failures "introspectable api" do
+      expect(version_mod).is_a?(Module)
+      expect(version_mod).to(have_version_constant)
+      expect(version_mod).to(have_version_as_string)
+      expect(version_mod.to_s).to(be_a(String))
+      expect(version_mod).to(have_epoch_as_integer)
+      expect(version_mod).to(have_major_as_integer)
+      expect(version_mod).to(have_minor_as_integer)
+      expect(version_mod).to(have_patch_as_integer)
+      expect(version_mod).to(have_pre_as_nil_or_string)
+      expect(version_mod.to_h.keys).to(match_array(%i[epoch major minor patch pre]))
+      expect(version_mod.to_a).to(be_a(Array))
+    end
+  end
+end

data/lib/version_gem/ruby.rb

@@ -1,16 +1,21 @@
+# frozen_string_literal: true
+
 module VersionGem
   # Helpers for library CI integration against many different versions of Ruby
   module Ruby
     RUBY_VER = ::Gem::Version.new(RUBY_VERSION)
 
+    # Check if the current Ruby version is greater than or equal to the given version
     def gte_minimum_version?(version, engine = "ruby")
       RUBY_VER >= ::Gem::Version.new(version) && ::RUBY_ENGINE == engine
     end
     module_function :gte_minimum_version?
 
+    # Check if the current Ruby version (MAJOR.MINOR) is equal to the given version
     def actual_minor_version?(major, minor, engine = "ruby")
-      major.to_i == RUBY_VER.segments[0] &&
-        minor.to_i == RUBY_VER.segments[1] &&
+      segs = RUBY_VER.segments
+      major.to_i == segs[0] &&
+        minor.to_i == segs[1] &&
         ::RUBY_ENGINE == engine
     end
     module_function :actual_minor_version?

data/lib/version_gem/version.rb

@@ -2,11 +2,13 @@
 
 module VersionGem
   module Version
-    VERSION = "1.1.3"
+    VERSION = "1.1.9"
     # This would work in this gem, but not in external libraries,
     #   because version files are loaded in Gemspecs before bundler
     #   has a chance to load dependencies.
     # Instead, see lib/version_gem.rb for a solution that will work everywhere
     # extend VersionGem::Basic
+    #   or
+    # extend VersionGem::Epoch
   end
 end

data/lib/version_gem.rb

@@ -2,6 +2,7 @@
 
 require_relative "version_gem/version"
 require_relative "version_gem/basic"
+require_relative "version_gem/epoch"
 
 # Namespace of this library
 module VersionGem

data/sig/all_formatters.rbs

@@ -0,0 +1 @@
+ALL_FORMATTERS: bool

data/sig/debug.rbs

@@ -0,0 +1 @@
+DEBUG: bool

data/sig/debug_ide.rbs

@@ -0,0 +1 @@
+DEBUG_IDE: bool

data/sig/debug_jruby.rbs

@@ -0,0 +1 @@
+DEBUG_JRUBY: bool

data/sig/debugging.rbs

@@ -0,0 +1 @@
+DEBUGGING: bool

data/sig/run_coverage.rbs

@@ -0,0 +1 @@
+RUN_COVERAGE: bool

data/sig/version_gem/api.rbs

@@ -0,0 +1,27 @@
+module VersionGem
+  module Api
+    # Internal memoized version string segments
+    @_to_a: Array[String]
+
+    # Memoized components
+    @major: Integer
+    @minor: Integer
+    @patch: Integer
+    @pre: String?
+    @to_a: Array[Integer | String | nil]
+    @to_h: Hash[Symbol, (Integer | String | nil)]
+
+    # Public API
+    def to_s: () -> String
+    def major: () -> Integer
+    def minor: () -> Integer
+    def patch: () -> Integer
+    def pre: () -> String?
+    def to_a: () -> Array[Integer | String | nil]
+    def to_h: () -> Hash[Symbol, (Integer | String | nil)]
+
+    private
+
+    def _to_a: () -> Array[String]
+  end
+end

data/sig/version_gem/basic.rbs

@@ -0,0 +1,5 @@
+module VersionGem
+  module Basic
+    def self.extended: () -> void
+  end
+end

data/sig/version_gem/epoch.rbs

@@ -0,0 +1,26 @@
+module VersionGem
+  module Epoch
+    EPOCH_SIZE: Integer
+
+    # Hook used when this module is extended
+    def self.extended: (untyped) -> void
+
+    module OverloadApiForEpoch
+      # The epoch component (derived)
+      def epoch: () -> Integer
+
+      # Override of Api#major returning the derived major component
+      def major: () -> Integer
+
+      # Hash representation including epoch
+      def to_h: () -> Hash[Symbol, (Integer | String | nil)]
+
+      # Array of components [epoch, major, minor, patch, pre]
+      def to_a: () -> Array[Integer | String | nil]
+
+      private
+
+      def _major: () -> Integer
+    end
+  end
+end

data/sig/version_gem/error.rbs

@@ -0,0 +1,4 @@
+module VersionGem
+  class Error < ::RuntimeError
+  end
+end

data/sig/version_gem/ruby.rbs

@@ -0,0 +1,11 @@
+module VersionGem
+  module Ruby
+    RUBY_VER: ::Gem::Version
+
+    # Check if the current Ruby version is >= given version for the engine
+    def self.gte_minimum_version?: (String, ?String) -> bool
+
+    # Check if the current Ruby MAJOR.MINOR equals the given values for the engine
+    def self.actual_minor_version?: ((Integer | String), (Integer | String), ?String) -> bool
+  end
+end

data/sig/version_gem/version.rbs

@@ -0,0 +1,9 @@
+module VersionGem
+  module Version
+    VERSION: String
+
+    # At runtime this module is extended with Basic via class_eval in lib/version_gem.rb
+    # Declare the intended extension so class methods are available in typing
+    extend VersionGem::Basic
+  end
+end

data/sig/version_gem.rbs

@@ -0,0 +1,2 @@
+module VersionGem
+end