Add ContinuousBuildCodeFormatter for continuous-trunk Android versionCodes (#735)

Author: oguzkocer

CHANGELOG.md

@@ -11,6 +11,7 @@ _None_
 ### New Features
 
 - Added `find_or_create_pull_request` action and `GithubHelper#find_pull_request`: returns the URL of the open Pull Request for a head branch, creating one only if none exists yet. Useful for "rolling" automations (e.g. a daily translations or dependency-update job) that force-push the same head branch on every run. [#733]
+- Added `ContinuousBuildCodeFormatter`, which derives an Android Play Store `versionCode` for a "continuous trunk" release model as `(major * 10 + minor) * 10^build_digits + build_number` (default `build_digits: 6`). It encodes a high-cardinality, monotonically increasing build number (e.g. a Buildkite build number) that `DerivedBuildCodeFormatter` cannot hold, validates that `minor <= 9`, and guards against exceeding the Play Store's maximum `versionCode`. [#735]
 
 ### Bug Fixes
 

lib/fastlane/plugin/wpmreleasetoolkit/versioning/formatters/continuous_build_code_formatter.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Fastlane
+  module Wpmreleasetoolkit
+    module Versioning
+      # Google Play Store's maximum allowed versionCode.
+      MAX_PLAY_STORE_VERSION_CODE = 2_100_000_000
+
+      # The `ContinuousBuildCodeFormatter` derives an Android Play Store `versionCode` for a
+      # "continuous trunk" release model, where the low-order term is a high-cardinality,
+      # monotonically increasing build number (e.g. a Buildkite build number).
+      #
+      # The build code is computed as:
+      #
+      #   versionCode = (major * 10 + minor) * 10^build_digits + build_number
+      #
+      # It takes `major`, `minor`, and `build_number` as explicit arguments rather than an
+      # `AppVersion`, because the inputs come from different sources and an `AppVersion` does not
+      # model them: the marketing `major`/`minor` come from the parsed version, while `build_number`
+      # is an independent CI counter (e.g. `BUILDKITE_BUILD_NUMBER`). Notably, `AppVersion#build_number`
+      # means something else in this domain (the RC/beta iteration counter, e.g. `-rc-1`), so taking an
+      # `AppVersion` here would invite reading the wrong field. There is also no `patch`: in a
+      # continuous-trunk model the build number strictly orders every build and subsumes patch's
+      # ordering role (hotfixes get a new build number, not a patch digit in the code).
+      #
+      # Because the build number is globally monotonic and the version prefix only ever increases,
+      # the resulting code is always strictly increasing — even if the build number eventually
+      # exceeds `10^build_digits` (which only costs human-readability, not ordering). The only hard
+      # correctness constraint is staying at or below the Play Store's max versionCode.
+      #
+      # Unlike `DerivedBuildCodeFormatter` (fixed-width string concatenation capped at 8 total digits
+      # and 3 digits per component, i.e. build <= 999), this formatter can hold a large build number.
+      # The two formatters target different release models; this one does not replace the other.
+      class ContinuousBuildCodeFormatter
+        # @param [Integer] build_digits Number of digits reserved for the build number, which sets the
+        # multiplier applied to the `major * 10 + minor` prefix (multiplier = 10^build_digits).
+        # Must be a positive integer. Defaults to 6 (multiplier = 1_000_000).
+        #
+        def initialize(build_digits: 6)
+          validate_build_digits!(build_digits)
+          @build_digits = build_digits
+        end
+
+        # Derive the build code (Android `versionCode`).
+        #
+        # @param [Integer] major The major (marketing) version number.
+        # @param [Integer] minor The minor (marketing) version number. Must be 9 or lower.
+        # @param [Integer] build_number A high-cardinality, monotonically increasing build number
+        # (e.g. a Buildkite build number). This is a CI counter, not `AppVersion#build_number`.
+        #
+        # @return [Integer] The derived `versionCode`.
+        #
+        def build_code(major:, minor:, build_number:)
+          # Validate up front so bad input (e.g. strings from env vars or file reads) raises a
+          # user-friendly error rather than an opaque `TypeError` from the arithmetic below.
+          validate_component!('major', major)
+          validate_component!('minor', minor)
+          validate_component!('build_number', build_number)
+
+          # `major * 10 + minor` is only unambiguous while minor is a single digit.
+          if minor > 9
+            UI.user_error!("Minor version (#{minor}) must be 9 or lower to derive an unambiguous build code with `#{self.class.name}`")
+          end
+
+          prefix = (major * 10) + minor
+          code = (prefix * (10**@build_digits)) + build_number
+
+          # Sanity check: Play Store versionCodes must be positive integers.
+          if code <= 0
+            UI.user_error!("Derived build code (#{code}) must be a positive integer")
+          end
+
+          if code > MAX_PLAY_STORE_VERSION_CODE
+            UI.user_error!("Derived build code (#{code}) exceeds the maximum allowed Play Store versionCode (#{MAX_PLAY_STORE_VERSION_CODE})")
+          end
+
+          code
+        end
+
+        private
+
+        # Validates that a version component is a non-negative integer.
+        #
+        # @param [String] name The component name, used in the error message
+        # @param [Integer] value The value to validate
+        #
+        # @raise [StandardError] If the value is not a non-negative integer
+        #
+        def validate_component!(name, value)
+          unless value.is_a?(Integer)
+            UI.user_error!("`#{name}` must be an integer, got: #{value.class}")
+          end
+
+          return unless value.negative?
+
+          UI.user_error!("`#{name}` must be a non-negative integer, got: #{value}")
+        end
+
+        # Validates that `build_digits` is a positive integer.
+        #
+        # @param [Integer] build_digits The build digit count to validate
+        #
+        # @raise [StandardError] If the value is not a positive integer
+        #
+        def validate_build_digits!(build_digits)
+          unless build_digits.is_a?(Integer)
+            UI.user_error!("`build_digits` must be an integer, got: #{build_digits.class}")
+          end
+
+          return if build_digits.positive?
+
+          UI.user_error!("`build_digits` must be a positive integer, got: #{build_digits}")
+        end
+      end
+    end
+  end
+end

spec/continuous_build_code_formatter_spec.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Fastlane::Wpmreleasetoolkit::Versioning::ContinuousBuildCodeFormatter do
+  describe 'derives a versionCode' do
+    it 'encodes major, minor and build number with the default build_digits (6)' do
+      expect(described_class.new.build_code(major: 26, minor: 9, build_number: 84_231)).to eq(269_084_231)
+    end
+
+    it 'returns an Integer' do
+      expect(described_class.new.build_code(major: 26, minor: 9, build_number: 84_231)).to be_a(Integer)
+    end
+  end
+
+  describe 'monotonicity' do
+    it 'increases with the build number within the same version' do
+      formatter = described_class.new
+      expect(formatter.build_code(major: 26, minor: 9, build_number: 84_232))
+        .to be > formatter.build_code(major: 26, minor: 9, build_number: 84_231)
+    end
+
+    it 'increases across a version bump even when the build number also increases' do
+      formatter = described_class.new
+      expect(formatter.build_code(major: 27, minor: 0, build_number: 84_232))
+        .to be > formatter.build_code(major: 26, minor: 9, build_number: 84_231)
+    end
+  end
+
+  describe 'custom build_digits' do
+    it 'applies the configured multiplier (10^build_digits)' do
+      # (2 * 10 + 6) * 10^4 + 123 = 26 * 10_000 + 123 = 260_123
+      expect(described_class.new(build_digits: 4).build_code(major: 2, minor: 6, build_number: 123)).to eq(260_123)
+    end
+  end
+
+  # The build number is allowed to exceed 10^build_digits. The docstring guarantees ordering still
+  # holds in that case (overflow "only costs human-readability, not ordering") *because* the build
+  # number is globally monotonic. These lock that in — and guard against a future change such as
+  # masking the build number with `% 10**build_digits`, which would silently break ordering.
+  context 'when the build number overflows its reserved digits (10^build_digits)' do
+    it 'still increases within the same version across the overflow boundary' do
+      formatter = described_class.new(build_digits: 4) # 10^4 = 10_000
+      # 269 * 10_000 + 10_000 = 2_700_000   vs   269 * 10_000 + 9_999 = 2_699_999
+      expect(formatter.build_code(major: 26, minor: 9, build_number: 10_000))
+        .to be > formatter.build_code(major: 26, minor: 9, build_number: 9_999)
+    end
+
+    it 'still increases across a version bump while both build numbers are past the overflow point' do
+      formatter = described_class.new(build_digits: 4) # 10^4 = 10_000
+      # 270 * 10_000 + 25_001 = 2_725_001   vs   269 * 10_000 + 25_000 = 2_715_000
+      expect(formatter.build_code(major: 27, minor: 0, build_number: 25_001))
+        .to be > formatter.build_code(major: 26, minor: 9, build_number: 25_000)
+    end
+
+    it 'can render identically to a later version once overflowed — the documented readability cost, which is harmless under a monotonic build number' do
+      formatter = described_class.new(build_digits: 4) # 10^4 = 10_000
+      # Overflow makes the digits ambiguous: 26.9 build 10_000 and 27.0 build 0 both come out as 2_700_000.
+      # That's the "only costs human-readability" caveat — and it's safe because a globally monotonic
+      # build number means (27, 0, build: 0) never *follows* (26, 9, build: 10_000); the counter only goes up.
+      expect(formatter.build_code(major: 26, minor: 9, build_number: 10_000))
+        .to eq(formatter.build_code(major: 27, minor: 0, build_number: 0))
+    end
+  end
+
+  describe 'validation' do
+    it 'raises when minor is greater than 9' do
+      expect { described_class.new.build_code(major: 26, minor: 10, build_number: 1) }
+        .to raise_error(/Minor version \(10\) must be 9 or lower/)
+    end
+
+    it 'raises when the derived code exceeds the Play Store maximum' do
+      # (210 * 10 + 0) * 10^6 = 2_100_000_000; +1 tips over the cap.
+      expect { described_class.new.build_code(major: 210, minor: 0, build_number: 1) }
+        .to raise_error(/exceeds the maximum allowed Play Store versionCode \(2100000000\)/)
+    end
+
+    it 'does not raise when the derived code is exactly at the Play Store maximum' do
+      expect(described_class.new.build_code(major: 210, minor: 0, build_number: 0)).to eq(2_100_000_000)
+    end
+
+    it 'raises when the derived code is not positive (all-zeros input)' do
+      expect { described_class.new.build_code(major: 0, minor: 0, build_number: 0) }
+        .to raise_error(/Derived build code \(0\) must be a positive integer/)
+    end
+
+    it 'rejects a non-integer build_digits' do
+      expect { described_class.new(build_digits: '6') }
+        .to raise_error(/`build_digits` must be an integer, got: String/)
+    end
+
+    it 'rejects a non-positive build_digits' do
+      expect { described_class.new(build_digits: 0) }
+        .to raise_error(/`build_digits` must be a positive integer, got: 0/)
+    end
+
+    %w[major minor build_number].each do |component|
+      it "rejects a non-integer #{component} with a user-friendly error" do
+        args = { major: 26, minor: 9, build_number: 84_231 }
+        args[component.to_sym] = '1' # e.g. an unparsed value from an env var or file read
+        expect { described_class.new.build_code(**args) }
+          .to raise_error(/`#{component}` must be an integer, got: String/)
+      end
+
+      it "rejects a negative #{component}" do
+        args = { major: 26, minor: 9, build_number: 84_231 }
+        args[component.to_sym] = -1
+        expect { described_class.new.build_code(**args) }
+          .to raise_error(/`#{component}` must be a non-negative integer, got: -1/)
+      end
+    end
+  end
+end