philiprehberger-version_compare 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a91bc47b98cf1f9c5e98b0318859928eb5b5b643f7e11731ed261dd8f6a36748
-  data.tar.gz: 0cf92cd231bcd7e9ecb5c11daf634ba49738ee9caaa2a8a74ad78830fa4ded53
+  metadata.gz: 450510c518a2b1269153611f05c0c7646b54d987854e76ff09e160454fd3477c
+  data.tar.gz: e33e54ef7cec42703e60708e71a8912c9a3e233e267f77b0c21648abb92ac2ac
 SHA512:
-  metadata.gz: 4f0fbf52e71a05e6aa26f689682690e0c97338cfa7a9efb3bfd79d99faaec7a6f6ca7dc67a73d4cecbb30a5708a1f0f12e15190bc320c30adb898ed2e6a8bb64
-  data.tar.gz: 839070f4538e9185b3e5d696befccc8b8ad60d209be8b00883cb9e64fa6379f81943d1601b85f7e17bbc4adbc3fb521108eb3ce2305ebd3a0bfd18bcf32102c3
+  metadata.gz: 44780be3cc465e16143cf75e161301088e8ce2c11533673771b68b40e059651badb02ff43d81badeb9118c0fd33218497c7f86e28e1c0dc185b0c278471227bf
+  data.tar.gz: 650c55ec56bcec915f9118d414b3afecf523b24cfc33889c9cc4a292dca4b7b2c53af08fbd36475c520d56eb6a7d8f9b3ff389682f8579863340e73c4dc9898b

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-20
+
+### Added
+- `VersionCompare.compatible?(baseline, candidate)` — SemVer API-compatibility check: same major and candidate >= baseline (pre-1.0 also requires matching minor)
+- Card image reference in the README for registry-side rendering
+
 ## [0.4.0] - 2026-04-25
 
 ### Added

data/README.md

@@ -4,6 +4,8 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-version_compare.svg)](https://rubygems.org/gems/philiprehberger-version_compare)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-version-compare)](https://github.com/philiprehberger/rb-version-compare/commits/main)
 
+![philiprehberger-version_compare](https://raw.githubusercontent.com/philiprehberger/rb-version-compare/main/package-card.webp)
+
 Version string parsing with comparison, sorting, and constraint matching
 
 ## Requirements
@@ -153,6 +155,23 @@ Philiprehberger::VersionCompare.highest_satisfying(versions, '>= 4.0.0')
 # => nil
 ```
 
+### API Compatibility Check
+
+```ruby
+# Same major + candidate >= baseline => compatible
+Philiprehberger::VersionCompare.compatible?("1.2.0", "1.5.3")  # => true
+
+# Different major => incompatible
+Philiprehberger::VersionCompare.compatible?("1.5.0", "2.0.0")  # => false
+
+# Below baseline => incompatible
+Philiprehberger::VersionCompare.compatible?("1.5.0", "1.4.9")  # => false
+
+# Pre-1.0.0 requires matching minor (matches `~>` semantics)
+Philiprehberger::VersionCompare.compatible?("0.3.0", "0.3.4")  # => true
+Philiprehberger::VersionCompare.compatible?("0.3.0", "0.4.0")  # => false
+```
+
 ## API
 
 ### `Philiprehberger::VersionCompare`
@@ -165,6 +184,7 @@ Philiprehberger::VersionCompare.highest_satisfying(versions, '>= 4.0.0')
 | `.filter(versions, constraint)` | Filter an array of version strings by a constraint |
 | `.highest_satisfying(versions, constraint)` | Return the highest version string that satisfies a constraint, or `nil` |
 | `.min(versions)` / `.max(versions)` | Lowest/highest version from a list |
+| `.compatible?(baseline, candidate)` | API-compatibility check: same major + candidate >= baseline (pre-1.0 also requires matching minor) |
 
 ### `SemanticVersion`
 

data/lib/philiprehberger/version_compare/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module VersionCompare
-    VERSION = '0.4.0'
+    VERSION = '0.5.0'
   end
 end

data/lib/philiprehberger/version_compare.rb

@@ -225,6 +225,30 @@ module Philiprehberger
       versions.select { |v| parse(v).satisfies?(constraint) }
     end
 
+    # Check whether two versions are API-compatible per SemVer.
+    #
+    # Two versions are considered compatible when:
+    # - both share the same major component, AND
+    # - the candidate is greater than or equal to the baseline (so it has every API
+    #   the baseline expects)
+    #
+    # When the baseline is pre-1.0.0 (major == 0), SemVer considers every minor bump
+    # potentially breaking; in that regime compatibility additionally requires the
+    # same minor component, matching the `~>` (pessimistic) constraint behavior.
+    #
+    # @param baseline [String, SemanticVersion] the version your code expects
+    # @param candidate [String, SemanticVersion] the version actually present
+    # @return [Boolean] true when `candidate` is API-compatible with `baseline`
+    def self.compatible?(baseline, candidate)
+      base = baseline.is_a?(SemanticVersion) ? baseline : parse(baseline)
+      cand = candidate.is_a?(SemanticVersion) ? candidate : parse(candidate)
+
+      return false unless base.major == cand.major
+      return false if cand < base
+
+      base.major.zero? ? base.minor == cand.minor : true
+    end
+
     # Return the highest version from an array that satisfies a constraint
     #
     # Performs a single pass over versions, tracking the maximum parsed

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-version_compare
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-26 00:00:00.000000000 Z
+date: 2026-05-20 00:00:00.000000000 Z
 dependencies: []
 description: Parse semantic version strings into comparable objects with support for
   sorting, finding the latest version, and checking constraint satisfaction.