bundler-overrule 0.2.0

data/lib/bundler/overrule.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "bundler"
+
+require_relative "overrule/version"
+require_relative "overrule/errors"
+require_relative "overrule/rule"
+require_relative "overrule/dependency_rewriter"
+require_relative "overrule/registry"
+require_relative "overrule/reporter"
+require_relative "overrule/patcher"
+require_relative "overrule/dsl"
+
+module Bundler
+  # Force, ban, and swap gem versions from your Gemfile.
+  #
+  # Nothing here patches Bundler until the first rule is declared: with no
+  # rules, resolution is byte-identical to vanilla Bundler (G4).
+  module Overrule
+    # Verified against 2.6.x, 2.7.x and 4.0.x. The upper bound is deliberately
+    # loose — Patcher also structurally verifies every patch target, which is a
+    # better guard than a version number, and refuses to run if one is missing.
+    #
+    # An Array, not a comma-joined String: Gem::Requirement.create(">= 2.6, < 5")
+    # raises BadRequirementError.
+    SUPPORTED_BUNDLER = [">= 2.6", "< 5"].freeze
+    SUPPORTED_BUNDLER_DESCRIPTION = SUPPORTED_BUNDLER.join(", ").freeze
+
+    class << self
+      def registry
+        @registry ||= Registry.new
+      end
+
+      def reporter
+        @reporter ||= Reporter.new(registry)
+      end
+
+      # Test hook.
+      def reset!
+        @registry = nil
+        @reporter = nil
+        @rules_changed = nil
+        @finalized = false
+        @definition_built = false
+        @suppress_summary = false
+        Patcher.reset!
+        self
+      end
+
+      def force(name, requirement, reason: nil)
+        register(Force.new(name, requirement, reason: reason))
+      end
+
+      def ban(name, reason: nil)
+        register(Ban.new(name, reason: reason))
+      end
+
+      def register(rule)
+        rule = registry.add(rule)
+        Patcher.apply!
+        rule
+      end
+
+      # 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).
+      def rewrite_gemfile_dependencies!(dependencies)
+        return dependencies if registry.empty? || dependencies.nil?
+
+        reject_banned_direct_dependencies!(dependencies)
+        apply_forces_to_gemfile!(dependencies)
+        dependencies
+      end
+
+      # Has the rule set changed since the lockfile was last written? Used to
+      # defeat Bundler's "lockfile looks current, skip resolution" fast path.
+      def rules_changed?
+        return false if registry.empty?
+        return @rules_changed unless @rules_changed.nil?
+
+        state = reporter.read_state
+        @rules_changed = state.nil? || state["fingerprint"] != registry.fingerprint
+      end
+
+      # True while Bundler is doing its pre-pass over the Gemfile looking for
+      # `plugin` lines (Bundler::Plugin.gemfile_install). Nothing is resolved
+      # in that pass.
+      def plugin_prepass?(dsl)
+        defined?(::Bundler::Plugin::DSL) && dsl.is_a?(::Bundler::Plugin::DSL)
+      end
+
+      def note_definition_built!
+        @definition_built = true
+      end
+
+      # `bundle overrule list` prints its own report; the install-time "YOU own
+      # the consequences" banner on top of it would just be noise.
+      def suppress_summary!
+        @suppress_summary = true
+      end
+
+      def suppress_summary?
+        @suppress_summary ||= false
+      end
+
+      def definition_built?
+        @definition_built ||= false
+      end
+
+      # Print the summary and persist the state file. Idempotent — it is
+      # reachable from both the plugin hook and the at_exit fallback.
+      def finalize!
+        return if @finalized || registry.empty? || !definition_built?
+
+        @finalized = true
+        reporter.print_summary unless suppress_summary?
+        reporter.write_state!
+      rescue StandardError => e
+        # Reporting must never be the thing that breaks an install.
+        ::Bundler.ui.warn("[bundler-overrule] could not write report: #{e.message}")
+      end
+
+      def active?
+        registry.any?
+      end
+
+      private
+
+      def reject_banned_direct_dependencies!(dependencies)
+        registry.bans.each do |rule|
+          next unless dependencies.any? { |dep| dep.name == rule.name }
+
+          raise BannedDirectDependencyError, <<~MSG
+            you can't ban `#{rule.name}` — your Gemfile requires it directly.
+
+            Remove the `gem '#{rule.name}'` line instead. `ban` is for gems pulled in
+            transitively by your other dependencies.
+          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

data/lib/bundler-overrule.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Bootstrap file — this is what a Gemfile requires.
+#
+#   plugin 'bundler-overrule'
+#   if (paths = Bundler::Plugin.index.load_paths('bundler-overrule'))
+#     $LOAD_PATH.unshift(*paths)
+#     require 'bundler-overrule'
+#   end
+#
+# Requiring this only makes `force` / `ban` available. No Bundler internals are
+# patched until a rule is actually declared.
+
+require_relative "bundler/overrule"
+
+Bundler::Dsl.prepend(Bundler::Overrule::Dsl) unless Bundler::Dsl.ancestors.include?(Bundler::Overrule::Dsl)
+
+# The rule summary is printed here, at exit, rather than from a Bundler plugin
+# hook. Bundler's earliest install-time hook (`before-install-all`) fires after
+# resolution but before installation, and some dependency edges are only read
+# during installation — reporting there would under-report which constraints
+# were actually rewritten. This runs for every Bundler command, including the
+# ones that never fire plugin hooks at all (`bundle lock`, `bundle check`).
+at_exit do
+  # $! is set when we are unwinding from an exception — a failed run should not
+  # be summarised as though the overrides took effect. Deliberately not using
+  # the English alias: this file is loaded during Gemfile evaluation in every
+  # bundle command, and it should require nothing it does not have to.
+  # rubocop:disable Style/SpecialGlobalVars
+  Bundler::Overrule.finalize! if $!.nil? && Bundler::Overrule.active?
+  # rubocop:enable Style/SpecialGlobalVars
+end

data/plugins.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Bundler plugin entrypoint. Bundler `load`s this file at plugin-install time
+# to discover which commands/hooks we register, and again at runtime whenever
+# one of them is needed.
+#
+# Note what is NOT here: the dependency-rewriting patches. No Bundler plugin
+# event fires before resolution, so hooks cannot influence it. The patches are
+# activated by the `require 'bundler-overrule'` line in the user's Gemfile,
+# which runs during Gemfile evaluation — before the resolver starts.
+
+require "bundler/plugin/api"
+
+# Registers `bundle overrule list` / `bundle overrule doctor`.
+class BundlerOverruleCommand < Bundler::Plugin::API
+  command "overrule"
+
+  def exec(_command, args)
+    require "bundler-overrule"
+    require "bundler/overrule/command"
+
+    exit(Bundler::Overrule::Command.new.call(args))
+  end
+end
+
+# Deliberately no hooks.
+#
+# `before-install-all` looks like the right place to print the rule summary —
+# it fires after resolution, before anything installs. It is not: some
+# dependency edges are only read during installation itself, so a summary
+# printed there under-reports and can claim a rule "matched nothing" when it in
+# fact rewrote the graph. The summary is emitted from an at_exit handler in
+# lib/bundler-overrule.rb instead, where the picture is complete.

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: bundler-overrule
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Nikhil Nelson
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  bundler-overrule is a Bundler plugin that gives application developers the final
+  say over their dependency graph. It adds `force` and `ban` to the Gemfile DSL:
+  `force` rewrites every version constraint on a gem, from other gems' gemspecs and
+  from your own Gemfile; `ban` removes a gem from resolution entirely. This is the
+  Ruby equivalent of Cargo's [patch], npm's overrides, and yarn's resolutions.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/bundler-overrule.rb
+- lib/bundler/overrule.rb
+- lib/bundler/overrule/command.rb
+- lib/bundler/overrule/dependency_rewriter.rb
+- lib/bundler/overrule/dsl.rb
+- lib/bundler/overrule/errors.rb
+- lib/bundler/overrule/patcher.rb
+- lib/bundler/overrule/registry.rb
+- lib/bundler/overrule/reporter.rb
+- lib/bundler/overrule/rule.rb
+- lib/bundler/overrule/version.rb
+- plugins.rb
+homepage: https://github.com/TheSoloHacker47/bundler-overrule
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/TheSoloHacker47/bundler-overrule
+  source_code_uri: https://github.com/TheSoloHacker47/bundler-overrule
+  changelog_uri: https://github.com/TheSoloHacker47/bundler-overrule/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/TheSoloHacker47/bundler-overrule/issues
+  documentation_uri: https://github.com/TheSoloHacker47/bundler-overrule#readme
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Force, ban, and swap gem versions in your Gemfile — the Bundler overrides
+  Cargo and npm already have.
+test_files: []