bundler-overrule 0.2.0

checksums.yaml

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

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned
+
+- `swap 'old', with: 'new'` — substitute an API-compatible fork published under a different name.
+- Windows CI.
+
+## [0.2.0] - 2026-08-16
+
+Initial public release. Ships `force` and `ban` together, because the documented
+quickstart uses both.
+
+### Added
+
+- `force NAME, REQUIREMENT, reason: nil` — rewrites every dependency edge pointing at `NAME`,
+  from other gems' gemspecs and from your own Gemfile.
+- `ban NAME, reason: nil` — removes a gem from resolution entirely.
+- `overrule do ... end` block form for grouping rules.
+- `bundle overrule list` — active rules and the exact constraints each one rewrote.
+- `bundle overrule doctor` — flags stale rules, an unsupported Bundler, and a missing
+  bootstrap line. Exits non-zero on problems, so it works as a CI check.
+- A one-line-per-rule summary printed on every `bundle install` / `bundle update`, including
+  which gem's constraint was overridden and the `reason:` you gave.
+- `.bundle/overrule-report.json` recording the rules and rewritten edges of the last
+  resolution. Nothing overrule-specific is ever written into `Gemfile.lock`.
+
+### Behavior notes
+
+- With no rules declared, zero patches are applied and resolution is byte-identical to
+  vanilla Bundler.
+- Two conflicting rules for one gem is a hard error; an identical re-declaration is not
+  (Bundler evaluates the Gemfile more than once per run).
+- Banning a gem the Gemfile requires directly is a hard error.
+- Editing a rule forces a re-resolve even when the Gemfile's own dependencies are unchanged,
+  which Bundler would otherwise skip.
+- Development dependencies are never rewritten or dropped.
+- 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
+[0.2.0]: https://github.com/TheSoloHacker47/bundler-overrule/releases/tag/v0.2.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikhil Nelson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,205 @@
+# bundler-overrule
+
+> Force, ban, and swap gem versions in your Gemfile — the dependency overrides that Cargo (`[patch]`), npm (`overrides`), and yarn (`resolutions`) have had for years, now for Bundler.
+
+[![Gem Version](https://badge.fury.io/rb/bundler-overrule.svg)](https://rubygems.org/gems/bundler-overrule)
+[![CI](https://github.com/TheSoloHacker47/bundler-overrule/actions/workflows/ci.yml/badge.svg)](https://github.com/TheSoloHacker47/bundler-overrule/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## The problem
+
+You try to upgrade one gem:
+
+```
+$ bundle update openssl
+# ...nothing happens
+```
+
+Because somewhere in your Gemfile, `web-push` pins `openssl ~> 2.2`. Upgrading `web-push`
+requires `jwt ~> 3.0`, which conflicts with four other gems pinned to `jwt ~> 2.0` — some of
+which haven't shipped a release in years. Your options today:
+
+- fork every blocking gem just to relax a one-line version constraint, and maintain those forks forever, or
+- point your Gemfile at git repos you don't control, or
+- give up.
+
+Pessimistic upper bounds (`~>`) are guesses about versions that didn't exist when they were
+written — and they're very often wrong. **Your Gemfile is your domain.** You should get the
+final say.
+
+## The fix
+
+```ruby
+# Gemfile
+source 'https://rubygems.org'
+
+plugin 'bundler-overrule'
+if (paths = Bundler::Plugin.index.load_paths('bundler-overrule'))
+  $LOAD_PATH.unshift(*paths)
+  require 'bundler-overrule'
+end
+
+gem 'rails'
+gem 'web-push'
+
+if defined?(Bundler::Overrule)
+  force 'openssl', '>= 3.0',
+        reason: 'web-push pins ~> 2.2 but works fine with 3.x (verified in CI)'
+
+  ban 'httpclient',
+      reason: 'unmaintained since 2016; vendored root certs expired'
+end
+```
+
+```
+$ bundle install
+[bundler-overrule] 2 rules active — YOU own the consequences of these overrides:
+  force openssl >= 3.0  (was: web-push → ~> 2.2)  # web-push pins ~> 2.2 but works fine with 3.x
+  ban   httpclient  (dropped from: jira-ruby)  # unmaintained since 2016; vendored root certs expired
+```
+
+Done. No forks. No `github:` pins. One honest, self-documenting line per override.
+
+## Installation
+
+```
+$ bundle plugin install bundler-overrule
+```
+
+Then add the bootstrap block shown above to the top of your Gemfile.
+
+Requires **Ruby >= 3.1** and **Bundler >= 2.6**. Full tested matrix in [CI](.github/workflows/ci.yml).
+
+### Why the Gemfile needs those extra lines
+
+Bundler plugins can't extend the Gemfile DSL on their own, so the `require` line is what makes
+`force` and `ban` available while your Gemfile is being evaluated. Two details matter:
+
+- **Guard the `require`.** `Bundler::Plugin.index.load_paths` returns `nil` — not an empty
+  array — when the plugin isn't installed. The `if` is what turns "plugin missing" into a
+  quiet no-op instead of a crash. Do **not** replace it with a trailing `rescue nil`: that
+  swallows real errors too, and you would get zero overrides with zero warning.
+- **Keep the `if defined?` guard.** On the very first `bundle install`, Bundler evaluates your
+  whole Gemfile once *before* installing any plugin, just to find the `plugin` lines. During
+  that pass `force`/`ban` don't exist yet. The guard skips them; the real evaluation pass a
+  moment later has the plugin loaded and applies them.
+
+## Usage
+
+### `force NAME, REQUIREMENT, reason: nil`
+
+Overrides **every** constraint on `NAME` — from other gems' gemspecs *and* from your own
+Gemfile — with `REQUIREMENT`. Bundler resolves as if everyone had asked for your version.
+
+```ruby
+force 'nokogiri', '~> 1.18'
+force 'rack', '>= 3.0', reason: 'CVE-2025-XXXXX; sinatra pin is stale'
+```
+
+### `ban NAME, reason: nil`
+
+Removes `NAME` from dependency resolution entirely. Useful for transitively-pulled gems you
+know your code paths never hit, or abandoned gems you've replaced.
+
+```ruby
+ban 'mimemagic', reason: 'we use marcel'
+```
+
+Banning a gem your Gemfile requires directly is an error — remove the `gem` line instead.
+
+### Block form
+
+Sugar for grouping; same registry underneath.
+
+```ruby
+overrule do
+  force 'openssl', '>= 3.0'
+  ban   'httpclient'
+end
+```
+
+### `swap OLD, with: NEW` *(v0.3 — roadmap)*
+
+Substitute a maintained, API-compatible fork published under a different name:
+
+```ruby
+swap 'httpclient', with: 'byroot-httpclient'
+```
+
+### Inspecting active rules
+
+```
+$ bundle overrule list      # every rule + exactly which constraints it rewrote
+$ bundle overrule doctor    # stale rules, unsupported Bundler, missing bootstrap line
+```
+
+`doctor` exits non-zero when it finds a problem, so it works as a CI check.
+
+## How it works
+
+`bundler-overrule` is a standard [Bundler plugin](https://bundler.io/guides/bundler_plugins.html).
+When (and only when) you declare a rule, it filters the dependency lists that gem specifications
+report to Bundler's resolver: `force` rewrites matching dependency requirements, `ban` drops
+them. The resolver itself is untouched, and your `Gemfile.lock` is a perfectly ordinary
+lockfile — deployment mode, `--frozen`, and CI caching all work unchanged.
+
+With no rules declared, the plugin applies **zero** patches and your resolution is byte-identical
+to vanilla Bundler (we test this — see scenario B7).
+
+Each run writes `.bundle/overrule-report.json` recording which edges were rewritten. That file
+is what `list` and `doctor` read; it is safe to delete and safe to gitignore. Nothing
+overrule-specific is ever written into `Gemfile.lock`.
+
+## Use responsibly
+
+An override is you telling Bundler "I know better than this gem's author." Sometimes you do —
+upper bounds are written before the future exists. But:
+
+- **Test the result.** You are opting out of the maintainer's compatibility promise.
+- **Write the `reason:`.** Your future self and your teammates will thank you.
+- **Don't report bugs upstream** for gem combinations their maintainers never declared support
+  for — reproduce without the override first.
+- Prefer deleting a rule once upstream relaxes the constraint (`bundle overrule doctor` flags
+  rules that no longer have any effect).
+
+## Compatibility
+
+| | |
+|---|---|
+| Ruby | 3.1, 3.2, 3.3, 3.4 |
+| Bundler | 2.6, 2.7, 4.0 (weekly CI run against latest) |
+| OS | Linux, macOS (Windows: best effort, CI planned) |
+
+Bundler 2.4 and 2.5 are not supported: they lack the internals this plugin relies on. There is
+no Bundler 3.x — the line went 2.7 → 4.0.
+
+If a new Bundler release moves the internals we patch, the plugin fails loudly with a clear
+message rather than silently mis-resolving. Pin your Bundler version in CI like you already should.
+
+## Roadmap
+
+- [x] v0.1 — `force`, warnings, `overrule list`
+- [x] v0.2 — `ban`, `overrule doctor`
+- [ ] v0.3 — `swap` (gem substitution)
+- [ ] Windows CI
+
+## Prior art & credits
+
+- [byroot's "The Missing Bundler Features"](https://byroot.github.io/ruby/bundler/2026/04/20/bundle-features.html) — this gem implements the `force`/ban/substitute semantics proposed there.
+- Longstanding Bundler feature requests: rubygems/bundler#1549 (2011), #2412 (2013), rubygems/rfcs#54.
+- [bundler-override](https://github.com/tarnowsc/bundler-override) and ManageIQ's bundler-inject — earlier takes on the same pain.
+- Cargo `[patch]`, npm `overrides`, pnpm/yarn `resolutions` — proof this belongs in every package manager.
+
+## Contributing
+
+Bug reports and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Quick start:
+
+```
+$ git clone https://github.com/TheSoloHacker47/bundler-overrule && cd bundler-overrule
+$ bin/setup
+$ bundle exec rake spec integration
+```
+
+## License
+
+[MIT](LICENSE).

data/lib/bundler/overrule/command.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Bundler
+  module Overrule
+    # `bundle overrule list` / `bundle overrule doctor`.
+    #
+    # Bundler hands plugin commands the raw ARGV tail, so option parsing is
+    # ours to do. There is very little of it on purpose.
+    class Command
+      SUBCOMMANDS = %w[list doctor].freeze
+
+      USAGE = <<~USAGE
+        Usage: bundle overrule SUBCOMMAND
+
+        Subcommands:
+          list      show every active rule and which dependency edges it rewrote
+          doctor    check for stale rules, an unsupported Bundler, a missing bootstrap line
+
+        Options:
+          -h, --help     show this message
+          -v, --version  show the bundler-overrule version
+      USAGE
+
+      def initialize(registry: nil, reporter: nil, out: $stdout)
+        @registry = registry
+        @reporter = reporter
+        @out = out
+      end
+
+      # @return [Integer] process exit status
+      def call(args)
+        subcommand = Array(args).first
+
+        return help(0) if subcommand.nil? || ["-h", "--help"].include?(subcommand)
+        return print_version if ["-v", "--version"].include?(subcommand)
+        return unknown_subcommand(subcommand) unless SUBCOMMANDS.include?(subcommand)
+
+        load_gemfile_rules
+        dispatch(subcommand)
+      end
+
+      private
+
+      def dispatch(subcommand)
+        case subcommand
+        when "list"
+          emit(reporter.list)
+          0
+        when "doctor"
+          emit(reporter.doctor)
+          reporter.healthy? ? 0 : 1
+        end
+      end
+
+      def emit(lines)
+        lines.each { |line| @out.puts(line) }
+      end
+
+      def print_version
+        @out.puts "bundler-overrule #{Overrule::VERSION}"
+        0
+      end
+
+      def unknown_subcommand(subcommand)
+        @out.puts "Unknown subcommand `#{subcommand}`."
+        @out.puts
+        help(1)
+      end
+
+      def registry
+        @registry ||= Overrule.registry
+      end
+
+      def reporter
+        @reporter ||= Overrule.reporter
+      end
+
+      def help(status)
+        @out.puts USAGE
+        status
+      end
+
+      # Evaluating the Gemfile is what registers the rules. Without it `list`
+      # could only ever report what the state file remembered.
+      def load_gemfile_rules
+        Overrule.suppress_summary!
+        return if registry.any?
+
+        ::Bundler.definition
+      rescue StandardError => e
+        @out.puts "[bundler-overrule] could not evaluate the Gemfile: #{e.message}"
+      end
+    end
+  end
+end

data/lib/bundler/overrule/dependency_rewriter.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Bundler
+  module Overrule
+    # One dependency edge that a rule actually changed.
+    #
+    # +owner+ is the gem whose gemspec declared the edge, or "Gemfile" for a
+    # direct dependency. +was+ / +now+ are requirement strings; +now+ is nil
+    # for a ban, because the edge is gone.
+    Edge = Struct.new(:rule, :owner, :was, :now) do
+      def banned?
+        now.nil?
+      end
+
+      def to_h
+        { "type" => rule.type.to_s, "gem" => rule.name, "owner" => owner,
+          "was" => was, "now" => now, "reason" => rule.reason }
+      end
+    end
+
+    # The heart of the gem: given a list of Gem::Dependency objects and a set
+    # of rules, return the rewritten list plus the edges that changed.
+    #
+    # Deliberately pure — no Bundler objects, no global state, no I/O — so the
+    # behavior contract can be unit-tested without running Bundler at all.
+    # Both the resolution seam and the installation seam call this same
+    # function, which is what keeps the lockfile and the installed gems from
+    # ever disagreeing about what a dependency list contains.
+    module DependencyRewriter
+      module_function
+
+      # @param dependencies [Array<Gem::Dependency>]
+      # @param rules_by_name [Hash{String => Rule}]
+      # @param owner [String, nil] gem name that declared these dependencies
+      # @return [Array(Array<Gem::Dependency>, Array<Edge>)]
+      def rewrite(dependencies, rules_by_name, owner: nil)
+        return [dependencies, []] if rules_by_name.empty? || dependencies.nil? || dependencies.empty?
+
+        edges = []
+        rewritten = []
+
+        dependencies.each do |dependency|
+          rule = rules_by_name[dependency.name]
+          replacement, edge = apply_rule(dependency, rule, owner)
+
+          rewritten << replacement unless replacement.nil?
+          edges << edge if edge
+        end
+
+        [rewritten, edges]
+      end
+
+      # Decide what one dependency becomes under one rule.
+      #
+      # @return [Array(Gem::Dependency, Edge)] the replacement (nil to drop the
+      #   dependency entirely) and the edge to record (nil if nothing changed)
+      def apply_rule(dependency, rule, owner)
+        # Development dependencies never reach the resolver, but spec objects
+        # still report them. Rewriting or dropping one would be a lie about
+        # what the gem declares, for no benefit.
+        return [dependency, nil] if rule.nil? || development?(dependency)
+
+        case rule.type
+        when :ban
+          [nil, Edge.new(rule, owner, requirement_string(dependency), nil)]
+        when :force
+          return [dependency, nil] if dependency.requirement == rule.requirement
+
+          [replace(dependency, rule.requirement),
+           Edge.new(rule, owner, requirement_string(dependency), rule.requirement.to_s)]
+        else
+          [dependency, nil]
+        end
+      end
+
+      def development?(dependency)
+        dependency.respond_to?(:type) && dependency.type == :development
+      end
+
+      def requirement_string(dependency)
+        dependency.requirement.to_s
+      end
+
+      # Swap in a new requirement while keeping everything else about the
+      # dependency intact.
+      #
+      # We copy-and-mutate rather than construct a fresh object on purpose.
+      # Bundler::Dependency derives #groups, #source, #git, #path, #github,
+      # #branch and #ref lazily from an options hash it keeps privately, and
+      # the shape of that hash has changed across Bundler versions. Rebuilding
+      # from public readers silently drops whichever of those we forgot — a
+      # `force` on a gem declared with `git:` would quietly lose its source.
+      # Duplicating preserves the exact class and every option, forever.
+      def replace(dependency, requirement)
+        replacement = dependency.dup
+        replacement.instance_variable_set(:@requirement, requirement)
+        replacement
+      end
+    end
+  end
+end

data/lib/bundler/overrule/dsl.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Bundler
+  module Overrule
+    # The Gemfile DSL. Prepended into Bundler::Dsl by the bootstrap file, which
+    # is why `force` and `ban` are callable at the top level of a Gemfile.
+    module Dsl
+      # Override every constraint on +name+ — from other gems' gemspecs and
+      # from your own Gemfile — with +requirement+.
+      #
+      #   force 'openssl', '>= 3.0', reason: 'web-push pins ~> 2.2; 3.x is fine'
+      def force(name, requirement, reason: nil)
+        Overrule.force(name, requirement, reason: reason)
+      end
+
+      # Remove +name+ from dependency resolution entirely.
+      #
+      #   ban 'httpclient', reason: 'unmaintained; vendored certs expired'
+      def ban(name, reason: nil)
+        Overrule.ban(name, reason: reason)
+      end
+
+      # Sugar for grouping rules. Same registry underneath.
+      #
+      #   overrule do
+      #     force 'openssl', '>= 3.0'
+      #     ban   'httpclient'
+      #   end
+      def overrule(&block)
+        raise ArgumentError, "overrule requires a block" unless block
+
+        instance_eval(&block)
+      end
+    end
+  end
+end

data/lib/bundler/overrule/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "bundler"
+
+module Bundler
+  module Overrule
+    # Base class for every error this plugin raises.
+    #
+    # Inherits Bundler::BundlerError so Bundler's friendly-error handler prints
+    # the message on its own, without a Ruby backtrace — these are all user
+    # mistakes in a Gemfile, not crashes.
+    class Error < ::Bundler::BundlerError
+      def status_code
+        59
+      end
+    end
+
+    # Raised when a rule is malformed: a bad requirement string, a blank gem
+    # name, an unusable +reason:+.
+    class InvalidRuleError < Error; end
+
+    # Raised when two conflicting rules target the same gem (B4).
+    class DuplicateRuleError < Error; end
+
+    # Raised when a `ban` targets a gem the Gemfile requires directly (B6).
+    class BannedDirectDependencyError < Error; end
+
+    # Raised when the running Bundler does not expose the internals we patch.
+    # We would rather abort loudly than silently mis-resolve (G5, B9).
+    class UnsupportedBundlerError < Error
+      def initialize(detail)
+        super(<<~MSG)
+          bundler-overrule does not support Bundler #{::Bundler::VERSION}.
+
+          #{detail}
+
+          Supported: Bundler #{Overrule::SUPPORTED_BUNDLER_DESCRIPTION}.
+
+          This is a deliberate hard stop. bundler-overrule rewrites dependency
+          edges by patching Bundler internals; if those internals have moved,
+          continuing could silently resolve the wrong versions. Pin your Bundler
+          version, or upgrade bundler-overrule if a newer release supports this one.
+        MSG
+      end
+    end
+  end
+end