bundler-overrule 0.2.0

data/lib/bundler/overrule/patcher.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Bundler
+  module Overrule
+    # Applies the monkey-patches, and refuses to run if Bundler's internals
+    # have moved somewhere we do not recognise.
+    #
+    # Two seams carry the whole feature:
+    #
+    #   1. Bundler::Dsl#to_definition — the Gemfile's own dependency list.
+    #      This is what makes `force` beat a `gem 'x', '1.5'` line (B2) and
+    #      what keeps the lockfile's DEPENDENCIES section honest.
+    #
+    #   2. #dependencies / #runtime_dependencies on the spec classes — every
+    #      transitive edge. BOTH readers matter: `runtime_dependencies` feeds
+    #      resolution (via MatchMetadata#expanded_dependencies) and
+    #      SpecSet#validate_deps, while `dependencies` feeds
+    #      ParallelInstaller::SpecInstallation#all_dependencies. Filtering only
+    #      the former resolves correctly and then deadlocks the installer,
+    #      which sits waiting for a banned gem that will never arrive.
+    #
+    # Patching the resolver itself (Resolver#to_dependency_hash) also works for
+    # resolution and is tempting as a single choke point, but it does not cover
+    # installation, so it buys nothing over seam 2 and adds a patch point.
+    module Patcher
+      # Spec classes whose dependency readers feed resolution and installation.
+      SPEC_CLASSES = %w[
+        Gem::Specification
+        Bundler::RemoteSpecification
+        Bundler::EndpointSpecification
+        Bundler::StubSpecification
+        Bundler::LazySpecification
+      ].freeze
+
+      class << self
+        def applied?
+          @applied ||= false
+        end
+
+        # Idempotent: Bundler 4.0 may re-load plugins.rb during a single run,
+        # and the Gemfile itself is evaluated more than once.
+        def apply!
+          return if applied?
+
+          verify_supported!
+          patch_dsl!
+          patch_spec_classes!
+          patch_resolve_short_circuit!
+          @applied = true
+        end
+
+        # Test hook. Prepended modules cannot be un-prepended; this only resets
+        # the "have we done it" flag, which is all the specs need.
+        def reset!
+          @applied = false
+        end
+
+        def verify_supported!
+          unless ::Gem::Requirement.create(SUPPORTED_BUNDLER).satisfied_by?(::Gem::Version.new(::Bundler::VERSION))
+            raise UnsupportedBundlerError, "Bundler #{::Bundler::VERSION} is outside the tested range."
+          end
+
+          missing = SPEC_CLASSES.reject { |name| resolve_constant(name) }
+          unless missing.empty?
+            raise UnsupportedBundlerError,
+                  "Expected these classes to exist, but they do not: #{missing.join(", ")}."
+          end
+
+          return if ::Bundler::Dsl.method_defined?(:to_definition)
+
+          raise UnsupportedBundlerError, "Bundler::Dsl#to_definition is missing."
+        end
+
+        private
+
+        def patch_dsl!
+          prepend_once(::Bundler::Dsl, GemfileDependencies)
+        end
+
+        def patch_spec_classes!
+          SPEC_CLASSES.each do |name|
+            klass = resolve_constant(name)
+            prepend_once(klass, SpecDependencies)
+          end
+        end
+
+        # Bundler skips resolution entirely when the lockfile looks current
+        # (Definition#no_resolve_needed?). A rule added or edited since the last
+        # run would then silently do nothing. Force a re-resolve when the rule
+        # set has changed since the lockfile was written.
+        def patch_resolve_short_circuit!
+          return unless ::Bundler::Definition.method_defined?(:no_resolve_needed?)
+
+          prepend_once(::Bundler::Definition, ResolveFreshness)
+        end
+
+        def prepend_once(klass, mod)
+          klass.prepend(mod) unless klass.ancestors.include?(mod)
+        end
+
+        def resolve_constant(name)
+          name.split("::").inject(Object) { |scope, part| scope.const_get(part, false) }
+        rescue NameError
+          nil
+        end
+      end
+
+      # Seam 1 — the Gemfile's own dependencies.
+      module GemfileDependencies
+        def to_definition(*args, **kwargs)
+          # Bundler evaluates the whole Gemfile once through Bundler::Plugin::DSL
+          # before any plugin is installed, purely to find `plugin` lines. That
+          # pass resolves nothing, so it must not count as a real run — otherwise
+          # every rule looks like it "matched nothing".
+          Overrule.note_definition_built! unless Overrule.plugin_prepass?(self)
+          Overrule.rewrite_gemfile_dependencies!(@dependencies)
+          super
+        end
+      end
+
+      # Seam 2 — every transitive edge, at both resolution and install time.
+      module SpecDependencies
+        def dependencies
+          Overrule.registry.filter(super, owner: name)
+        end
+
+        def runtime_dependencies
+          Overrule.registry.filter(super, owner: name)
+        end
+      end
+
+      # See Patcher.patch_resolve_short_circuit!
+      module ResolveFreshness
+        def no_resolve_needed?
+          return false if Overrule.rules_changed?
+
+          super
+        end
+      end
+    end
+  end
+end

data/lib/bundler/overrule/registry.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "errors"
+require_relative "rule"
+require_relative "dependency_rewriter"
+
+module Bundler
+  module Overrule
+    # Holds the rules declared in the Gemfile and the edges they rewrote.
+    #
+    # There is one of these per process (see Overrule.registry). It is not
+    # thread-safe by design: rules are declared during single-threaded Gemfile
+    # evaluation. Edge *recording* does happen from the parallel installer, so
+    # that path appends to a plain array and de-duplicates on read rather than
+    # locking on every dependency lookup.
+    class Registry
+      attr_reader :rules
+
+      def initialize
+        clear!
+      end
+
+      def clear!
+        @rules = []
+        @rules_by_name = {}
+        @edges = []
+        self
+      end
+
+      def empty?
+        @rules.empty?
+      end
+
+      def any?
+        !empty?
+      end
+
+      # Fast lookup used on the hot path (once per dependency, per spec).
+      attr_reader :rules_by_name
+
+      def add(rule)
+        existing = @rules_by_name[rule.name]
+
+        if existing
+          # Bundler evaluates the Gemfile more than once per invocation, so an
+          # identical re-declaration is expected and must be a no-op. Only a
+          # genuinely different rule for the same gem is an error (B4).
+          return existing if existing == rule
+
+          raise DuplicateRuleError, <<~MSG
+            duplicate overrule for `#{rule.name}`
+
+              already declared: #{existing}
+              then declared:    #{rule}
+
+            Each gem may have at most one overrule rule. Pick one and delete the other.
+          MSG
+        end
+
+        @rules << rule
+        @rules_by_name[rule.name] = rule
+        rule
+      end
+
+      def rule_for(name)
+        @rules_by_name[name]
+      end
+
+      def forces
+        @rules.select { |r| r.type == :force }
+      end
+
+      def bans
+        @rules.select { |r| r.type == :ban }
+      end
+
+      # Rewrite a dependency list and remember what changed.
+      def filter(dependencies, owner: nil)
+        return dependencies if empty?
+
+        rewritten, edges = DependencyRewriter.rewrite(dependencies, @rules_by_name, owner: owner)
+        @edges.concat(edges) unless edges.empty?
+        rewritten
+      end
+
+      # Every edge a rule actually changed, de-duplicated. Bundler asks specs
+      # for their dependencies many times per run, so the raw list is noisy.
+      def edges
+        @edges.uniq { |e| [e.rule.name, e.owner, e.was, e.now] }
+      end
+
+      def edges_for(rule)
+        edges.select { |e| e.rule.name == rule.name }
+      end
+
+      # Rules that matched nothing at all (B3) — `doctor` flags these.
+      def stale_rules
+        matched = edges.map { |e| e.rule.name }.uniq
+        @rules.reject { |r| matched.include?(r.name) }
+      end
+
+      # Identifies the current rule set. Written to the state file so we can
+      # tell when rules changed and a re-resolve is required (see Patcher).
+      def fingerprint
+        return nil if empty?
+
+        payload = @rules.map { |r| "#{r.type}:#{r.name}:#{r.comparable_requirement}" }.sort.join("\n")
+        # ::Digest — Bundler vendors its own Bundler::Digest, which would win here.
+        ::Digest::SHA256.hexdigest(payload)[0, 16]
+      end
+    end
+  end
+end

data/lib/bundler/overrule/reporter.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+require_relative "version"
+
+module Bundler
+  module Overrule
+    # Warnings, `overrule list` / `overrule doctor` output, and the state file.
+    #
+    # The exact warning text is part of this gem's user experience — it is the
+    # only thing standing between an override and a silent surprise — so it is
+    # asserted verbatim in the specs.
+    class Reporter
+      STATE_FILE = "overrule-report.json"
+      BANNER = "[bundler-overrule]"
+
+      TABLE_HEADERS = %w[TYPE GEM REQUIREMENT REASON].freeze
+      TABLE_KEYS = %w[type gem requirement reason].freeze
+      TABLE_SEPARATOR = "  "
+
+      def initialize(registry, ui: nil)
+        @registry = registry
+        @ui = ui
+      end
+
+      # The block printed during `bundle install` / `bundle update`.
+      def summary
+        return [] if @registry.empty?
+
+        header = "#{BANNER} #{pluralize(@registry.rules.size, "rule")} active — " \
+                 "YOU own the consequences of these overrides:"
+        [header, *@registry.rules.map { |rule| "  #{rule_line(rule)}" }]
+      end
+
+      def print_summary
+        lines = summary
+        return if lines.empty?
+
+        lines.each { |line| ui.warn(line) }
+      end
+
+      # `bundle overrule list`
+      def list
+        state = read_state
+        return ["#{BANNER} no rules are active.", "", hint_for_empty(state)] if @registry.empty? && state.nil?
+
+        rules = @registry.any? ? rules_from_registry : rules_from_state(state)
+        return ["#{BANNER} no rules are active."] if rules.empty?
+
+        out = ["#{BANNER} #{pluralize(rules.size, "rule")}:", ""]
+        out.concat(render_table(rules))
+        out << ""
+        out << if state
+                 "Edges below were recorded during the last resolution " \
+                   "(#{state["generated_at"]}, Bundler #{state["bundler_version"]})."
+               else
+                 "No resolution recorded yet — run `bundle install` to see which edges are rewritten."
+               end
+        out
+      end
+
+      # `bundle overrule doctor`
+      def doctor
+        problems = []
+        notes = []
+
+        problems.concat(check_bundler_supported)
+        problems.concat(check_bootstrap_present)
+        problems.concat(check_stale_rules)
+        notes.concat(check_state_freshness)
+
+        out = ["#{BANNER} doctor", ""]
+        if problems.empty?
+          out << "  ✓ no problems found"
+        else
+          problems.each { |p| out << "  #{p}" }
+        end
+        unless notes.empty?
+          out << ""
+          notes.each { |n| out << "  #{n}" }
+        end
+        out
+      end
+
+      def healthy?
+        check_bundler_supported.empty? && check_bootstrap_present.empty? && check_stale_rules.empty?
+      end
+
+      # ---- state file -------------------------------------------------------
+
+      def state_path
+        ::Bundler.app_config_path.join(STATE_FILE)
+      rescue StandardError
+        nil
+      end
+
+      def write_state!
+        path = state_path
+        return nil if path.nil? || @registry.empty?
+
+        payload = {
+          "schema" => 1,
+          "overrule_version" => Overrule::VERSION,
+          "bundler_version" => ::Bundler::VERSION,
+          "generated_at" => Time.now.utc.iso8601,
+          "fingerprint" => @registry.fingerprint,
+          "rules" => @registry.rules.map { |r| rule_to_h(r) },
+          "edges" => edges_to_persist
+        }
+
+        require "fileutils"
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, "#{JSON.pretty_generate(payload)}\n")
+        path
+      rescue SystemCallError
+        # A read-only checkout is not a reason to fail an install.
+        nil
+      end
+
+      def read_state
+        path = state_path
+        return nil if path.nil? || !File.exist?(path)
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError, SystemCallError
+        nil
+      end
+
+      private
+
+      # Not every Bundler invocation resolves. `bundle overrule list`, for
+      # instance, evaluates the Gemfile (registering rules) but never touches
+      # the resolver, so it records no edges. Persisting that empty list would
+      # erase the real resolution's record and make `doctor` declare every rule
+      # stale. Keep the previous edges whenever the rules themselves are
+      # unchanged.
+      def edges_to_persist
+        current = @registry.edges.map(&:to_h)
+        return current unless current.empty?
+
+        previous = read_state
+        return current if previous.nil? || previous["fingerprint"] != @registry.fingerprint
+
+        previous["edges"] || current
+      end
+
+      def ui
+        @ui || ::Bundler.ui
+      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 << "  #{provenance(rule)}"
+        line << "  # #{rule.reason}" if rule.reason
+        line
+      end
+
+      def provenance(rule)
+        edges = @registry.edges_for(rule)
+        return "(no effect — rule matched nothing)" if edges.empty?
+
+        owners = edges.map { |e| e.owner || "?" }.uniq
+        shown = owners.first(2).join(", ")
+        shown += ", +#{owners.size - 2} more" if owners.size > 2
+
+        if rule.type == :ban
+          "(dropped from: #{shown})"
+        else
+          was = edges.map(&:was).uniq.first(2).join(", ")
+          "(was: #{shown} → #{was})"
+        end
+      end
+
+      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 || "" }
+        end
+      end
+
+      def rules_from_state(state)
+        (state["rules"] || []).map do |r|
+          { "type" => r["type"], "gem" => r["gem"], "requirement" => r["requirement"] || "—",
+            "reason" => r["reason"] || "" }
+        end
+      end
+
+      def render_table(rows)
+        widths = column_widths(rows)
+
+        [
+          table_row(TABLE_HEADERS, widths),
+          widths.map { |width| "-" * width }.join(TABLE_SEPARATOR),
+          *rows.map { |row| table_row(TABLE_KEYS.map { |key| row[key].to_s }, widths) }
+        ]
+      end
+
+      def column_widths(rows)
+        TABLE_KEYS.each_with_index.map do |key, index|
+          [TABLE_HEADERS[index].length, *rows.map { |row| row[key].to_s.length }].max
+        end
+      end
+
+      def table_row(cells, widths)
+        cells.each_with_index.map { |cell, index| cell.ljust(widths[index]) }
+             .join(TABLE_SEPARATOR).rstrip
+      end
+
+      def rule_to_h(rule)
+        { "type" => rule.type.to_s, "gem" => rule.name,
+          "requirement" => (rule.type == :force ? rule.requirement.to_s : nil),
+          "reason" => rule.reason }
+      end
+
+      def check_bundler_supported
+        requirement = ::Gem::Requirement.create(Overrule::SUPPORTED_BUNDLER)
+        if requirement.satisfied_by?(::Gem::Version.new(::Bundler::VERSION))
+          []
+        else
+          ["✗ Bundler #{::Bundler::VERSION} is outside the supported range " \
+           "(#{Overrule::SUPPORTED_BUNDLER_DESCRIPTION})."]
+        end
+      end
+
+      def check_bootstrap_present
+        gemfile = ::Bundler.default_gemfile.read
+        return [] if gemfile.include?("bundler-overrule")
+
+        ["✗ your Gemfile has no bundler-overrule bootstrap line — rules will never load. " \
+         "See the README quickstart."]
+      rescue StandardError
+        []
+      end
+
+      def check_stale_rules
+        matched = matched_gem_names
+        # Nothing to judge against: no resolution has ever been recorded.
+        # Better to say so (check_state_freshness does) than to accuse every
+        # rule of being dead.
+        return [] if matched.nil?
+
+        @registry.rules.reject { |rule| matched.include?(rule.name) }.map do |rule|
+          "✗ `#{rule}` had no effect — nothing in the graph depends on `#{rule.name}`. " \
+            "Delete it."
+        end
+      end
+
+      # Which gems a rule actually touched. `bundle overrule doctor` evaluates
+      # the Gemfile but never resolves, so in that process the registry has no
+      # edges at all — the answer has to come from the last resolution's state
+      # file, or the command would report every rule as stale.
+      def matched_gem_names
+        return @registry.edges.map { |e| e.rule.name }.uniq unless @registry.edges.empty?
+
+        state = read_state
+        return nil if state.nil?
+
+        (state["edges"] || []).map { |e| e["gem"] }.uniq
+      end
+
+      def check_state_freshness
+        state = read_state
+        return ["· no resolution recorded yet — run `bundle install`."] if state.nil?
+
+        if @registry.any? && state["fingerprint"] != @registry.fingerprint
+          ["· rules changed since the last resolution — run `bundle install` to apply them."]
+        else
+          ["· last resolution: #{state["generated_at"]} (Bundler #{state["bundler_version"]})."]
+        end
+      end
+
+      def hint_for_empty(_state)
+        "Declare rules in your Gemfile with `force` / `ban`. See the README."
+      end
+
+      def pluralize(count, noun)
+        "#{count} #{noun}#{"s" unless count == 1}"
+      end
+    end
+  end
+end

data/lib/bundler/overrule/rule.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Bundler
+  module Overrule
+    # A single override declared in the Gemfile.
+    #
+    # Rules are immutable value objects. Equality is by content, which is what
+    # lets us tell a harmless Gemfile re-evaluation (Bundler evaluates the
+    # Gemfile more than once per run) apart from a genuine duplicate rule (B4).
+    class Rule
+      attr_reader :name, :reason
+
+      def initialize(name, reason: nil)
+        @name = normalize_name(name)
+        @reason = normalize_reason(reason)
+        freeze
+      end
+
+      # :force or :ban — subclasses define it.
+      def type
+        raise NotImplementedError
+      end
+
+      # Does this rule apply to the given dependency name?
+      def applies_to?(dependency_name)
+        name == dependency_name
+      end
+
+      def ==(other)
+        other.is_a?(Rule) && other.type == type && other.name == name &&
+          other.comparable_requirement == comparable_requirement
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, name, comparable_requirement].hash
+      end
+
+      # Rules that differ only by +reason:+ are still the same rule; we do not
+      # want to error on a re-run just because someone reworded a comment.
+      def comparable_requirement
+        nil
+      end
+
+      def to_s
+        raise NotImplementedError
+      end
+
+      private
+
+      def normalize_name(value)
+        string = value.to_s.strip
+        raise InvalidRuleError, "gem name can't be blank" if string.empty?
+
+        string
+      end
+
+      def normalize_reason(value)
+        return nil if value.nil?
+
+        string = value.to_s.strip
+        string.empty? ? nil : string
+      end
+    end
+
+    # `force 'openssl', '>= 3.0'` — rewrite every constraint on this gem.
+    class Force < Rule
+      attr_reader :requirement
+
+      def initialize(name, requirement, reason: nil)
+        @requirement = build_requirement(requirement)
+        super(name, reason: reason)
+      end
+
+      def type
+        :force
+      end
+
+      def comparable_requirement
+        requirement.to_s
+      end
+
+      def to_s
+        "force #{name} #{requirement}"
+      end
+
+      private
+
+      def build_requirement(value)
+        raise InvalidRuleError, "force '#{value}' requires a version requirement" if value.nil?
+
+        ::Gem::Requirement.create(value)
+      rescue ::Gem::Requirement::BadRequirementError => e
+        raise InvalidRuleError, "invalid version requirement #{value.inspect}: #{e.message}"
+      end
+    end
+
+    # `ban 'httpclient'` — drop every edge pointing at this gem.
+    class Ban < Rule
+      def type
+        :ban
+      end
+
+      def to_s
+        "ban #{name}"
+      end
+    end
+  end
+end

data/lib/bundler/overrule/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Bundler
+  module Overrule
+    VERSION = "0.2.0"
+  end
+end