bundler-overrule 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 211e077f4842c7fe2b966596c15fb5a368855c82c6b5c766e3d716f9cf330c59
-  data.tar.gz: caa8412b3e12623347571872404eb6e462fa0d7978fda22d5c9c0b0896a0e0a9
+  metadata.gz: 0f11226dad5e167fb6701cd49f045369b8e30bce7a3684b6cec799bf57410f24
+  data.tar.gz: d554c6fe335658e875f0ec8a0468045b45f51ab815bf27f88ceb94bf8b615b66
 SHA512:
-  metadata.gz: 7d157303868882f4a3bccb4d931d9e4451fce5f535137a28ebaf0174788615eb3858db8ea3301dac0e89b461ac0eb0fd714bb37cca9431fe667efd29e7f8b62d
-  data.tar.gz: 759bf851a997b806005a4afa326ce520adce55fb0f267122ca5c1b5b03f3032e4d7ca20a7513e6f1fad9a752800eeb65f25f79f0a658537da6055e55b1cd59c5
+  metadata.gz: 90d88393f5dcc4a9ebbe3ad5731a0d8100f8edf0bcff1a850b366e1e09054bac66e56875751981a0e8a31b1191abed065e7eec4f0ba1015b79e6cfd27ad44eb4
+  data.tar.gz: b612931c189d30877225b49c0e041559f4919032f07a76acc22d79e7082ffa0bb9c8091dc7ddee0112ac2776ad6d59ca4a17ea7b6dd4cf1b26f67f9bedeed66a

data/CHANGELOG.md

@@ -9,9 +9,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Planned
 
-- `swap 'old', with: 'new'` — substitute an API-compatible fork published under a different name.
 - Windows CI.
 
+## [0.3.0] - 2026-08-16
+
+### Added
+
+- `swap OLD, with: NEW, version: nil, reason: nil` — points every dependency edge at a
+  different gem, typically a maintained fork published under another name. Applies to
+  transitive edges and to a gem your own Gemfile declares directly.
+- `version:` constrains the substitute. Without it the substitute resolves at `>= 0`.
+  This is the only way to pin a swapped-in gem: `force` cannot do it, because `force` only
+  rewrites edges that already exist and nothing in the graph names the substitute yet.
+- `swap` rules appear in the install summary, `overrule list`, `overrule doctor` and the
+  state file, which now records the substitute's name.
+
+### Behavior notes
+
+- The substitute does **not** inherit the original edge's requirement. A fork's version
+  numbers are its own lineage, and carrying `~> 2.8` onto a fork that restarted at 1.0
+  would be unresolvable for a reason the user never wrote down.
+- Unlike `ban`, `swap` on a directly declared gem is allowed and rewrites the `gem` line —
+  it is a substitution, so it applies everywhere.
+- Options that located the *old* gem (`git:`, `path:`, `source:`, `branch:`, `ref:`, …) are
+  dropped when substituting; `group:`, `platforms:` and `require:` are kept.
+- Swapping a gem with itself is rejected.
+- `swap` is install-time only. It does **not** alias `require` at runtime — that would mean
+  shipping code into production, which this gem does not do. The substitute must ship a
+  compatible require path.
+
 ## [0.2.0] - 2026-08-16
 
 Initial public release. Ships `force` and `ban` together, because the documented
@@ -44,5 +70,6 @@ quickstart uses both.
 - An unsupported Bundler aborts before resolution rather than patching internals it does not
   recognise.
 
-[Unreleased]: https://github.com/TheSoloHacker47/bundler-overrule/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/TheSoloHacker47/bundler-overrule/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/TheSoloHacker47/bundler-overrule/releases/tag/v0.3.0
 [0.2.0]: https://github.com/TheSoloHacker47/bundler-overrule/releases/tag/v0.2.0

data/README.md

@@ -114,18 +114,38 @@ Sugar for grouping; same registry underneath.
 ```ruby
 overrule do
   force 'openssl', '>= 3.0'
-  ban   'httpclient'
+  ban   'mimemagic'
+  swap  'httpclient', with: 'byroot-httpclient'
 end
 ```
 
-### `swap OLD, with: NEW` *(v0.3 — roadmap)*
+### `swap OLD, with: NEW, version: nil, reason: nil`
 
-Substitute a maintained, API-compatible fork published under a different name:
+Point every edge at a different gem — typically a maintained fork published under another
+name. Works on transitively-pulled gems and on gems your own Gemfile declares.
 
 ```ruby
-swap 'httpclient', with: 'byroot-httpclient'
+swap 'httpclient', with: 'byroot-httpclient', reason: 'unmaintained since 2016'
+swap 'httpclient', with: 'byroot-httpclient', version: '~> 3.0'
 ```
 
+Two things worth knowing:
+
+- **The substitute does not inherit the original's version requirement.** A fork's version
+  numbers are its own lineage, so carrying `~> 2.8` onto a fork that restarted at 1.0 would
+  be unresolvable for a reason you never wrote down. The substitute resolves at `>= 0` unless
+  you pass `version:`. That keyword is the only way to pin it — `force` can't, because force
+  only rewrites edges that already exist and nothing in your graph names the fork yet.
+- **`swap` does not alias `require`.** This is an install-time tool; nothing is loaded in
+  your app at runtime, by design. So the substitute must ship the same require path — that
+  is, `require 'httpclient'` must keep working because the fork provides `lib/httpclient.rb`.
+  Forks published as drop-in replacements normally do. If yours doesn't, use `bundle add`
+  and change your `require` lines instead.
+
+Options that located the old gem (`git:`, `path:`, `source:`, `branch:`, `ref:`) are dropped
+when substituting, since they pointed at the gem you just replaced. `group:`, `platforms:`
+and `require:` are kept.
+
 ### Inspecting active rules
 
 ```
@@ -180,7 +200,7 @@ message rather than silently mis-resolving. Pin your Bundler version in CI like
 
 - [x] v0.1 — `force`, warnings, `overrule list`
 - [x] v0.2 — `ban`, `overrule doctor`
-- [ ] v0.3 — `swap` (gem substitution)
+- [x] v0.3 — `swap` (gem substitution)
 - [ ] Windows CI
 
 ## Prior art & credits

data/lib/bundler/overrule/dependency_rewriter.rb

@@ -68,6 +68,10 @@ module Bundler
 
           [replace(dependency, rule.requirement),
            Edge.new(rule, owner, requirement_string(dependency), rule.requirement.to_s)]
+        when :swap
+          [substitute(dependency, rule.replacement, rule.requirement),
+           Edge.new(rule, owner, requirement_string(dependency),
+                    "#{rule.replacement} #{rule.requirement}")]
         else
           [dependency, nil]
         end
@@ -96,6 +100,26 @@ module Bundler
         replacement.instance_variable_set(:@requirement, requirement)
         replacement
       end
+
+      # Options on a Gemfile dependency that describe *which gem*, as opposed to
+      # how it is used. A swap points at a different gem, so these must not be
+      # carried over — `gem 'httpclient', git: '...'` swapped to a fork would
+      # otherwise fetch the fork's name from the old gem's git remote.
+      LOCATOR_OPTIONS = %w[
+        source git github gist bitbucket path branch ref tag glob submodules
+      ].freeze
+
+      # Point a dependency at a different gem entirely, keeping the options that
+      # still make sense (groups, platforms, the require path).
+      def substitute(dependency, name, requirement)
+        unless dependency.is_a?(::Bundler::Dependency)
+          return ::Gem::Dependency.new(name, requirement, dependency.type)
+        end
+
+        options = dependency.instance_variable_get(:@options) || {}
+        kept = options.reject { |key, _| LOCATOR_OPTIONS.include?(key.to_s) }
+        ::Bundler::Dependency.new(name, requirement.as_list, kept)
+      end
     end
   end
 end

data/lib/bundler/overrule/dsl.rb

@@ -20,6 +20,18 @@ module Bundler
         Overrule.ban(name, reason: reason)
       end
 
+      # Substitute a different gem for +name+ everywhere it is depended on —
+      # typically a maintained fork published under another name.
+      #
+      #   swap 'httpclient', with: 'byroot-httpclient'
+      #   swap 'httpclient', with: 'byroot-httpclient', version: '~> 3.0'
+      #
+      # The substitute must ship the same require path; this is an install-time
+      # tool and does not alias `require` at runtime.
+      def swap(name, with:, version: nil, reason: nil)
+        Overrule.swap(name, with: with, version: version, reason: reason)
+      end
+
       # Sugar for grouping rules. Same registry underneath.
       #
       #   overrule do

data/lib/bundler/overrule/registry.rb

@@ -76,6 +76,10 @@ module Bundler
         @rules.select { |r| r.type == :ban }
       end
 
+      def swaps
+        @rules.select { |r| r.type == :swap }
+      end
+
       # Rewrite a dependency list and remember what changed.
       def filter(dependencies, owner: nil)
         return dependencies if empty?

data/lib/bundler/overrule/reporter.rb

@@ -15,6 +15,7 @@ module Bundler
     class Reporter
       STATE_FILE = "overrule-report.json"
       BANNER = "[bundler-overrule]"
+      RULE_LABELS = { force: "force", ban: "ban  ", swap: "swap " }.freeze
 
       TABLE_HEADERS = %w[TYPE GEM REQUIREMENT REASON].freeze
       TABLE_KEYS = %w[type gem requirement reason].freeze
@@ -151,14 +152,20 @@ module Bundler
       end
 
       def rule_line(rule)
-        label = rule.type == :force ? "force" : "ban  "
-        subject = rule.type == :force ? "#{rule.name} #{rule.requirement}" : rule.name
-        line = "#{label} #{subject}"
+        line = "#{RULE_LABELS.fetch(rule.type, rule.type.to_s)} #{rule_subject(rule)}"
         line << "  #{provenance(rule)}"
         line << "  # #{rule.reason}" if rule.reason
         line
       end
 
+      def rule_subject(rule)
+        case rule.type
+        when :force then "#{rule.name} #{rule.requirement}"
+        when :swap  then "#{rule.name} → #{rule.replacement}#{" #{rule.requirement}" if rule.pinned?}"
+        else rule.name
+        end
+      end
+
       def provenance(rule)
         edges = @registry.edges_for(rule)
         return "(no effect — rule matched nothing)" if edges.empty?
@@ -167,8 +174,11 @@ module Bundler
         shown = owners.first(2).join(", ")
         shown += ", +#{owners.size - 2} more" if owners.size > 2
 
-        if rule.type == :ban
+        case rule.type
+        when :ban
           "(dropped from: #{shown})"
+        when :swap
+          "(substituted in: #{shown})"
         else
           was = edges.map(&:was).uniq.first(2).join(", ")
           "(was: #{shown} → #{was})"
@@ -178,8 +188,15 @@ module Bundler
       def rules_from_registry
         @registry.rules.map do |rule|
           { "type" => rule.type.to_s, "gem" => rule.name,
-            "requirement" => (rule.type == :force ? rule.requirement.to_s : "—"),
-            "reason" => rule.reason || "" }
+            "requirement" => table_requirement(rule), "reason" => rule.reason || "" }
+        end
+      end
+
+      def table_requirement(rule)
+        case rule.type
+        when :force then rule.requirement.to_s
+        when :swap  then "→ #{rule.replacement}#{" #{rule.requirement}" if rule.pinned?}"
+        else "—"
         end
       end
 
@@ -213,7 +230,8 @@ module Bundler
 
       def rule_to_h(rule)
         { "type" => rule.type.to_s, "gem" => rule.name,
-          "requirement" => (rule.type == :force ? rule.requirement.to_s : nil),
+          "requirement" => (rule.respond_to?(:requirement) ? rule.requirement.to_s : nil),
+          "replacement" => (rule.type == :swap ? rule.replacement : nil),
           "reason" => rule.reason }
       end
 

data/lib/bundler/overrule/rule.rb

@@ -107,5 +107,59 @@ module Bundler
         "ban #{name}"
       end
     end
+
+    # `swap 'httpclient', with: 'byroot-httpclient'` — point every edge at a
+    # different gem instead.
+    #
+    # The substitute defaults to `>= 0` rather than inheriting the original
+    # edge's requirement: a fork's version numbers are its own lineage, and
+    # carrying `~> 2.8` onto a fork that restarted at 1.0 would be
+    # unresolvable for reasons the user never wrote down. Pass `version:` to
+    # constrain it.
+    class Swap < Rule
+      DEFAULT_REQUIREMENT = ">= 0"
+
+      attr_reader :replacement, :requirement
+
+      def initialize(name, replacement, version: nil, reason: nil)
+        @replacement = normalize_replacement(replacement, name)
+        @requirement = build_requirement(version || DEFAULT_REQUIREMENT)
+        super(name, reason: reason)
+      end
+
+      def type
+        :swap
+      end
+
+      def comparable_requirement
+        "#{replacement} #{requirement}"
+      end
+
+      # True when the caller pinned the substitute, rather than taking `>= 0`.
+      def pinned?
+        requirement != ::Gem::Requirement.create(DEFAULT_REQUIREMENT)
+      end
+
+      def to_s
+        pinned? ? "swap #{name} with #{replacement} #{requirement}" : "swap #{name} with #{replacement}"
+      end
+
+      private
+
+      def normalize_replacement(value, original)
+        replacement = normalize_name(value)
+        if replacement == normalize_name(original)
+          raise InvalidRuleError, "swap '#{replacement}' with itself does nothing"
+        end
+
+        replacement
+      end
+
+      def build_requirement(value)
+        ::Gem::Requirement.create(value)
+      rescue ::Gem::Requirement::BadRequirementError => e
+        raise InvalidRuleError, "invalid version requirement #{value.inspect}: #{e.message}"
+      end
+    end
   end
 end

data/lib/bundler/overrule/version.rb

@@ -2,6 +2,6 @@
 
 module Bundler
   module Overrule
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/bundler/overrule.rb

@@ -55,6 +55,10 @@ module Bundler
         register(Ban.new(name, reason: reason))
       end
 
+      def swap(name, with:, version: nil, reason: nil)
+        register(Swap.new(name, with, version: version, reason: reason))
+      end
+
       def register(rule)
         rule = registry.add(rule)
         Patcher.apply!
@@ -64,14 +68,16 @@ module Bundler
       # Called from the Dsl#to_definition seam with the Gemfile's own
       # dependency array, which we mutate in place.
       #
-      # `force` has to beat a Gemfile pin (B2), and `ban` of a directly
-      # required gem is a user error, not something to silently honour (B6).
+      # `force` has to beat a Gemfile pin (B2) and `swap` has to substitute a
+      # directly declared gem (B13), so both run over the Gemfile's own list
+      # through the same rewriter every other edge uses. `ban` is the exception:
+      # banning a gem you directly require is a user error, not something to
+      # silently honour (B6).
       def rewrite_gemfile_dependencies!(dependencies)
         return dependencies if registry.empty? || dependencies.nil?
 
         reject_banned_direct_dependencies!(dependencies)
-        apply_forces_to_gemfile!(dependencies)
-        dependencies
+        dependencies.replace(registry.filter(dependencies, owner: "Gemfile"))
       end
 
       # Has the rule set changed since the lockfile was last written? Used to
@@ -140,19 +146,6 @@ module Bundler
           MSG
         end
       end
-
-      def apply_forces_to_gemfile!(dependencies)
-        registry.forces.each do |rule|
-          index = dependencies.index { |dep| dep.name == rule.name }
-          next if index.nil?
-
-          existing = dependencies[index]
-          next if existing.requirement == rule.requirement
-
-          registry.filter([existing], owner: "Gemfile")
-          dependencies[index] = DependencyRewriter.replace(existing, rule.requirement)
-        end
-      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bundler-overrule
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Nikhil Nelson