bundler-resolutions 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a9bc7c0b4191b262edcc52111b78fb8c67b74b0c9642ddec0036142d46c2989
-  data.tar.gz: bb5c955b6db7a14e56e8d5048c98709a36f634f25364a14cbe22d6606d3faeab
+  metadata.gz: 7a6def9961c77861086b6b58177a934945938362e2125ba5dc49b8a6c06efdff
+  data.tar.gz: ccef554f38761f9916843d675f70ef7189ef8a7070bdb3d9b2e466e2eed998de
 SHA512:
-  metadata.gz: 2d0f016d3a21dd98fe3d175d015fd4e526a514f32acf8283205db330ac9e52df4444e59a12e761882580790c8bccc1599739d3375291f598b810b4e7800b0705
-  data.tar.gz: cf1c8bee485fa053ec3de1ac094638381d9153796de7e77f5add4ee31953f41889f3563f6413830a5351633cb2f7960d5557447f66d52aca69ac175293696646
+  metadata.gz: '01507905d1b9402c1efc92f9509b5aeef2b858d18c3b3e8555af937e1b479dc4b2711f87eed3ef87b8d64bfb7285bb299322a5925d43013e6dac6afa2128b5ba'
+  data.tar.gz: c85660a42a9149ffcded4f649ef8b2d9413da63eb435d9c8231be3fcdf26dc6aebea0a6608bd1206298ac3caf47b01681a573cecc4e92b0dc3b6638a893b219d

data/README.md

@@ -5,7 +5,7 @@ bundler-resolutions
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 [bundler-resolutions](https://github.com/hlascelles/bundler-resolutions) is a [bundler](https://bundler.io/)
-plugin that allows you to specify gem version requirements in your `Gemfile` without explicitly declaring
+plugin that allows you to specify gem version requirements for your `Gemfile` without explicitly declaring
 a concrete dependency on those gems. It acts much like the
 [resolutions](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/) feature in
 [Yarn](https://yarnpkg.com/).
@@ -15,54 +15,68 @@ a concrete dependency on those gems. It acts much like the
 
 ## Usage
 
-Add `bundler-resolutions` to your Gemfile, and add a `resolutions` group to specify the gems you
-want to specify versions requirements for.
+Add `bundler-resolutions` to your Gemfile, and add a `.bundler-resolutions.yml` file to
+specify the gems you want to specify versions requirements for.
 
-The resulting `Gemfile.lock` in this example will have nokogiri locked to `1.16.5` or above.
+### Example 1
 
-```ruby
-plugin 'bundler-resolutions'
-
-gem "rails"
+In this example the resulting `Gemfile.lock` will have nokogiri locked to `1.16.5` or above, but
+nokogiri will not be present in the `DEPENDENCIES` section of the lock file. Also, if `rails` were
+to change to a version that did not depend on nokogiri, then the resolution would not be used or
+appear in the lock file at all.
 
-group :resolutions do
-  gem "nokogiri", ">= 1.16.5" # CVE-2024-34459
-end
+`.bundler-resolutions.yml`:
+```yaml
+gems:
+  nokogiri: ">= 1.16.5" # CVE-2024-34459
 ```
 
-However the `Gemfile.lock` from this example will not have nokogiri at all, as it is neither
-explicitly declared, nor brought in as a transitive dependency.
-
+`Gemfile`:
 ```ruby
-plugin 'bundler-resolutions'
-
-group :resolutions do
-  gem "nokogiri", ">= 1.16.5" # CVE-2024-34459
-end
+gem 'bundler-resolutions'
+gem "rails"
 ```
 
-## Detail
+### Example 2
 
-`bundler-resolutions` allows you to specify version requirements using standard gem syntax in your
-Gemfile to indicate that you have version requirements for those gems *if* they were to be brought
-in as transitive dependencies, but that you don't depend on them yourself directly.
+Here, the `Gemfile.lock` from this example will not have nokogiri at all, as it is neither
+explicitly declared in the Gemfile, nor brought in as a transitive dependency.
 
-An example use case is in the Gemfile given below. Here we are saying that although we do not use nokogiri
-specifically ourselves, we want to ensure that if it is pulled in by other gems then it will
-always be above the know version with a CVE.
+`.bundler-resolutions.yml`:
+```yaml
+gems:
+  nokogiri: ">= 1.16.5" # CVE-2024-34459
+```
 
 ```ruby
-source "https://rubygems.org"
+gem 'bundler-resolutions'
+gem "thor"
+```
 
-plugin 'bundler-resolutions'
+## Config file
 
-gem "rails"
+The config file is a YAML file with a `gems` key that contains a mapping of gem names to version
+requirements. The version requirements are the same as those used in the `Gemfile`.
+
+Example:
 
-group :resolutions do
-  gem "nokogiri", ">= 1.16.5" # CVE-2024-34459
-end
+```yaml
+gems:
+  nokogiri: ">= 1.16.5" # CVE-2024-34459
+  thor: ">= 1.0.1, < 2.0"
 ```
 
+By default, `bundler-resolutions` will look for a file named `.bundler-resolutions.yml` in the
+current directory, or the parent, and continue looking up to the root dir.
+
+You can also specify a file location by setting the `BUNDLER_RESOLUTIONS_CONFIG` ENV var.
+
+## Detail
+
+`bundler-resolutions` allows you to specify version requirements in a config file 
+to indicate that you have version requirements for those gems *if* they were to be brought
+in as transitive dependencies, but that you don't depend on them yourself directly.
+
 The big difference between doing this and just declaring it in your Gemfile is that it will only 
 be used in resolutions (and be written to your lock file) if the gems you do directly depend on
 continue to use it. If they stop using it, then your resolutions will take no part in the
@@ -73,19 +87,24 @@ present in the `DEPENDENCIES` section of the lock file, as it is not a direct de
 
 ## Use cases
 
-There are a number of reasons you may want to prevent the usage of some gem versions, without
-direct use, such as:
+There are a number of reasons you may want to prevent the usage of some gem versions, but without
+declaring their direct use in Gemfiles. Also there are reasons to set versions across a monorepo
+of many Gemfiles, but where not all apps use all blessed versions, such as:
 
 1. You have learnt of a CVE of a gem.
-2. You have internal processes that mandate the usage of certain gem versions for legal or sign off reasons.
-3. You know of gem incompatibilities in later versions.
-4. You know that different OS architectures do not work with some versions.
+1. You have internal processes that mandate the usage of certain gem versions for legal or sign off reasons.
+1. You wish to take a paranoid approach to updating certain high value target gems. eg `devise`.
+1. You want certain gem collections to move in lockstep. eg `sinatra`, `rack` and `rack-protection`, which are relatively tightly coupled.
+1. You know of gems that are very slow to install and you have preinstalled them in internal base images. eg `rugged` or `sorbet`.
+1. You know of gems that are tightly coupled to ruby itself that shouldn't be upgraded. eg `stringio` and `psych`.
+1. You know of gem incompatibilities with your codebase in their later versions.
+1. You know that different OS architectures do not work with some versions.
+1. You wish to prevent unintentional downgrades of dependencies when using `bundle` commands.
 
 ## How it works
 
-`bundler-resolutions` works by patching the Gemfile DSL to allow for special processing
-of the `resolutions` group. It also patches the bundler `filtered_versions_for` method to
-allow for the resolution restrictions from the versions specified in the `resolutions` group.
+`bundler-resolutions` works by patching the `bundler` `Resolver` `filtered_versions_for` method to
+allow for the resolution restrictions from the versions specified in the config file.
 
 This is a very early version, and it should be considered experimental.
 

data/lib/bundler/resolutions/config.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Bundler
+  class Resolutions
+    class Config
+      CONFIG_FILE_NAME = ".bundler-resolutions.yml"
+
+      class << self
+        def load_config(config = nil)
+          raw_hash = if config.is_a?(Hash)
+                       config
+                     else
+                       YAML.safe_load_file(find_config(config))
+                     end
+          gems = raw_hash.fetch("gems")
+          gems.transform_values { |version| Gem::Requirement.new(version.split(",")) }
+        end
+
+        private def find_config(config = nil)
+          return config if config # If present, assume it is a location
+
+          # Use the ENV if present
+          env_file = ENV["BUNDLER_RESOLUTIONS_CONFIG"]
+          return env_file if env_file
+
+          # Otherwise find it in the file tree
+          dir = Dir.pwd
+          until File.exist?(File.join(dir, CONFIG_FILE_NAME))
+            dir = File.dirname(dir)
+            raise "Could not find #{CONFIG_FILE_NAME}" if dir == "/"
+          end
+          File.join(dir, CONFIG_FILE_NAME)
+        end
+      end
+    end
+  end
+end

data/lib/bundler/resolutions/version.rb

@@ -4,6 +4,6 @@ require_relative "../resolutions"
 
 module Bundler
   class Resolutions
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/bundler/resolutions.rb

@@ -1,47 +1,114 @@
 # frozen_string_literal: true
 
+require "yaml"
+require_relative "resolutions/config"
+
 module Bundler
   class Resolutions
-    GROUP_NAME = :resolutions
-
-    attr_reader :resolutions
+    DEFAULT_GEM_REQUIREMENT = Gem::Requirement.default
 
-    def initialize
-      @resolutions = {}
-    end
+    attr_reader :config
 
-    # This method is called by the DSL to set the resolution for a given gem. It is effectively
-    # an override of the normal gem method.
-    def gem(name, requirements)
-      resolutions[name.to_sym] = requirements
+    def initialize(config = nil)
+      @config = Bundler::Resolutions::Config.load_config(config)
     end
 
     class << self
-      def instance = @instance ||= new
+      def instance
+        @instance ||= new
+      end
     end
 
     # A module we prepend to Bundler::Resolutions::Resolver
+    # :reek:ModuleInitialize
     module Resolver
+      # Override the initializer in the resolver
+      def initialize(*args)
+        Bundler::Resolutions.instance.add_concrete_resolutions_for(args.first)
+        super
+      end
+
       # This overrides the default behaviour of the resolver to filter out versions that don't
-      # satisfy the requirements specified in RESOLVER_RESOLUTIONS.
+      # satisfy the requirements specified in .bundler-resolutions.yml.
       def filtered_versions_for(package)
-        super.select do |pkg|
-          req = Bundler::Resolutions.instance.resolutions[package.name.to_sym]
-          req ? Gem::Requirement.new(*req.split(",")).satisfied_by?(pkg.version) : true
+        Bundler::Resolutions.instance.constrain_versions_for(super, package)
+      end
+    end
+
+    def constrain_versions_for(results, package)
+      results.select do |pkg|
+        req = resolutions_for(package.name)
+        if req
+          log("making sure #{package} is satisfied by #{req}")
+          req.satisfied_by?(pkg.version)
+        else
+          true
         end
       end
     end
 
-    # A module we prepend to Bundler::Dsl
-    module Dsl
-      # Here we override the normal group function to capture the resolutions, and ensure any
-      # gem calls are effectively a no-op as regards to adding them to dependencies.
-      def group(*args, &blk)
-        args.first == GROUP_NAME ? Bundler::Resolutions.instance.instance_eval(&blk) : super
+    def add_concrete_resolutions_for(base)
+      base.requirements.each do |bundler_dependency|
+        requirement_name = bundler_dependency.name
+        resolutions = resolutions_for(requirement_name)
+
+        if resolutions
+          log(<<~MSG, requirement_name)
+            has resolutions for concrete dependency '#{requirement_name}': #{resolutions}
+          MSG
+        else
+          log("has no resolutions for concrete dependency '#{requirement_name}'", requirement_name)
+          next
+        end
+
+        bundler_resolutions_reqs = resolutions.requirements
+        apply_resolutions_for_concrete_gem(bundler_dependency, bundler_resolutions_reqs)
+      end
+    end
+
+    private def resolutions_for(package_name)
+      config[package_name]
+    end
+
+    # You can debug with BUNDLER_RESOLUTIONS_DEBUG=gem_name or BUNDLER_RESOLUTIONS_DEBUG=true
+    # to see all messages.
+    private def log(message, gem = nil)
+      return unless ENV["BUNDLER_RESOLUTIONS_DEBUG"]
+      return if gem && !ENV["BUNDLER_RESOLUTIONS_DEBUG"].split(",").include?(gem)
+
+      puts "bundler-resolutions: #{message}"
+    end
+
+    private def apply_resolutions_for_concrete_gem(bundler_dependency, bundler_resolutions_reqs)
+      requirement_name = bundler_dependency.name
+      bundler_resolutions_reqs.each do |r|
+        # If the concrete requirement is already in the Gemfile, skip it
+        requirements = bundler_dependency.requirement.requirements
+        if requirements.include?(r)
+          # We don't want to double up / dupe the same requirements
+          log(<<~MSG, requirement_name)
+            Skipping adding requirements to gem concretely specified in Gemfile as it
+            was already present: #{requirement_name}: #{bundler_dependency}
+          MSG
+          next
+        end
+
+        # Otherwise add the additional requirement
+        before_req = bundler_dependency.to_s
+        # If there were no requirements before, there is a default one for ">= 0". We need to
+        # remove that so when we add the new one the implicit ">= 0" is not present, as it normally
+        # isn't written out to lockfiles.
+        requirements.clear if bundler_dependency.requirement == DEFAULT_GEM_REQUIREMENT
+        # Add the new requirement
+        requirements << r
+        after_req = bundler_dependency.to_s
+
+        log(<<~MSG, requirement_name)
+          Adding concrete constraints for #{requirement_name}. Before: #{before_req}. After: #{after_req}.
+        MSG
       end
     end
   end
 end
 
 Bundler::Resolver.prepend(Bundler::Resolutions::Resolver)
-Bundler::Dsl.prepend(Bundler::Resolutions::Dsl)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bundler-resolutions
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Harry Lascelles
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-02 00:00:00.000000000 Z
+date: 2025-05-03 00:00:00.000000000 Z
 dependencies: []
 description: A bundler plugin to enforce resolutions without specifying a concrete
   dependency
@@ -20,6 +19,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/bundler/resolutions.rb
+- lib/bundler/resolutions/config.rb
 - lib/bundler/resolutions/version.rb
 - plugins.rb
 homepage: https://github.com/hlascelles/bundler-resolutions
@@ -32,7 +32,6 @@ metadata:
   source_code_uri: https://github.com/hlascelles/bundler-resolutions/
   bug_tracker_uri: https://github.com/hlascelles/bundler-resolutions/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -40,15 +39,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.6
 specification_version: 4
 summary: A bundler plugin to enforce resolutions without specifying a concrete dependency
 test_files: []