Summarize cooldown-skipped versions at the end of install, update, and lock

When cooldown silently resolves an older version, users comparing
environments with different cooldown settings can't tell why they got
different versions. Collect the versions the resolver excluded, and after a
successful resolution print the newest skipped version per gem once the
command finishes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: hsbt

lib/bundler/cli/common.rb

@@ -20,6 +20,17 @@ def self.print_post_install_message(name, msg)
       Bundler.ui.info msg
     end
 
+    def self.output_cooldown_skipped_summary(definition = Bundler.definition)
+      skipped = definition.cooldown_skipped
+      return if skipped.empty?
+
+      Bundler.ui.info "The following gem versions were skipped by the cooldown setting:"
+      skipped.each do |entry|
+        days = entry[:available_in_days]
+        Bundler.ui.info "  * #{entry[:name]} #{entry[:version]} (available in #{days} #{days == 1 ? "day" : "days"}), resolved #{entry[:resolved]} instead"
+      end
+    end
+
     def self.output_fund_metadata_summary
       return if Bundler.settings["ignore_funding_requests"]
       definition = Bundler.definition

lib/bundler/cli/install.rb

@@ -64,6 +64,7 @@ def run
       end
 
       Bundler::CLI::Common.output_post_install_messages installer.post_install_messages
+      Bundler::CLI::Common.output_cooldown_skipped_summary(definition)
 
       if CLI::Common.clean_after_install?
         require_relative "clean"

lib/bundler/cli/lock.rb

@@ -77,6 +77,8 @@ def run
           puts "Writing lockfile to #{file}"
           definition.write_lock(file, false)
         end
+
+        Bundler::CLI::Common.output_cooldown_skipped_summary(definition)
       end
 
       Bundler.ui.output_stream = previous_output_stream

lib/bundler/cli/update.rb

@@ -126,6 +126,7 @@ def run
       Bundler.ui.confirm "Bundle updated!"
       Bundler::CLI::Common.output_without_groups_message(:update)
       Bundler::CLI::Common.output_post_install_messages installer.post_install_messages
+      Bundler::CLI::Common.output_cooldown_skipped_summary
 
       Bundler::CLI::Common.output_fund_metadata_summary
     end

lib/bundler/definition.rb

@@ -372,6 +372,12 @@ def spec_git_paths
       sources.git_sources.filter_map {|s| File.realpath(s.path) if File.exist?(s.path) }
     end
 
+    # Versions excluded by cooldown during the last resolution, one entry per
+    # gem with the newest skipped version. Empty when no resolution ran.
+    def cooldown_skipped
+      @cooldown_skipped || []
+    end
+
     def groups
       dependencies.flat_map(&:groups).uniq
     end
@@ -783,6 +789,8 @@ def start_resolution
 
       result = SpecSet.new(resolver.start)
 
+      @cooldown_skipped = resolver.cooldown_skipped
+
       @resolved_bundler_version = result.find {|spec| spec.name == "bundler" }&.version
 
       @new_platforms.each do |platform|

lib/bundler/resolver.rb

@@ -14,11 +14,15 @@ class Resolver
     require_relative "resolver/root"
     require_relative "resolver/strategy"
 
+    attr_reader :cooldown_skipped
+
     def initialize(base, gem_version_promoter, most_specific_locked_platform = nil)
       @source_requirements = base.source_requirements
       @base = base
       @gem_version_promoter = gem_version_promoter
       @most_specific_locked_platform = most_specific_locked_platform
+      @cooldown_skipped = []
+      @cooldown_skipped_specs = {}
     end
 
     def start
@@ -36,6 +40,8 @@ def setup_solver
       root = Resolver::Root.new(name_for_explicit_dependency_source)
       root_version = Resolver::Candidate.new(0)
 
+      @cooldown_skipped_specs = {}
+
       @all_specs = Hash.new do |specs, name|
         source = source_for(name)
         matches = source.specs.search(name)
@@ -83,7 +89,9 @@ def solve_versions(root:, logger:)
       result = solver.solve
       resolved_specs = result.flat_map {|package, version| version.to_specs(package, @most_specific_locked_platform) }
       Override.attach(resolved_specs, @base.overrides)
-      SpecSet.new(resolved_specs).specs_with_additional_variants_from(@base.locked_specs)
+      spec_set = SpecSet.new(resolved_specs).specs_with_additional_variants_from(@base.locked_specs)
+      @cooldown_skipped = cooldown_skipped_summary(spec_set)
+      spec_set
     rescue Gem::PubGrub::SolveFailure => e
       incompatibility = e.incompatibility
 
@@ -447,6 +455,7 @@ def cooldown_excluded_versions(specs)
       specs.each do |spec|
         next unless cooldown_excluded?(spec)
         excluded[[spec.name, spec.version]] = true
+        (@cooldown_skipped_specs ||= {})[[spec.name, spec.version]] ||= spec
       end
       excluded
     end
@@ -489,6 +498,50 @@ def cooldown_now
       @cooldown_now ||= Time.now
     end
 
+    # Reports, per gem, the newest version that cooldown kept out of a
+    # successful resolution. A skipped version is only worth reporting when it
+    # is newer than the version actually resolved and satisfies every
+    # requirement the final resolution places on that gem, so we don't claim a
+    # version the resolver could never have picked anyway.
+    def cooldown_skipped_summary(spec_set)
+      return [] if @cooldown_skipped_specs.empty?
+
+      requirements = Hash.new {|h, name| h[name] = [] }
+      @requirements.each {|dep| requirements[dep.name] << dep.requirement }
+      spec_set.each do |spec|
+        spec.dependencies.each {|dep| requirements[dep.name] << dep.requirement }
+      end
+
+      resolved_versions = {}
+      spec_set.each do |spec|
+        version = resolved_versions[spec.name]
+        resolved_versions[spec.name] = spec.version if version.nil? || spec.version > version
+      end
+
+      newest_skipped = {}
+      @cooldown_skipped_specs.each do |(name, version), spec|
+        resolved = resolved_versions[name]
+        next unless resolved && version > resolved
+        next unless requirements[name].all? {|req| req.satisfied_by?(version) }
+        newest = newest_skipped[name]
+        newest_skipped[name] = spec if newest.nil? || version > newest.version
+      end
+
+      newest_skipped.values.sort_by(&:name).map do |spec|
+        {
+          name: spec.name,
+          version: spec.version,
+          resolved: resolved_versions[spec.name],
+          available_in_days: remaining_cooldown_days(spec),
+        }
+      end
+    end
+
+    def remaining_cooldown_days(spec)
+      remaining = (spec.remote.effective_cooldown * 86_400) - (cooldown_now - spec.created_at)
+      [(remaining / 86_400.0).ceil, 1].max
+    end
+
     def filter_remote_specs(specs, package)
       if package.prefer_local?
         local_specs = specs.select {|s| s.is_a?(StubSpecification) }

spec/install/cooldown_spec.rb

@@ -188,6 +188,84 @@
       expect(the_bundle).to include_gems("ripe_gem 2.0.0")
     end
 
+    it "summarizes skipped versions at the end of bundle install" do
+      gemfile <<-G
+        source "https://gem.repo3"
+        gem "ripe_gem"
+      G
+
+      bundle "install --cooldown 7", artifice: "compact_index_cooldown"
+
+      expect(out).to include("The following gem versions were skipped by the cooldown setting:")
+      expect(out).to include("* ripe_gem 2.0.0 (available in 6 days), resolved 1.0.0 instead")
+      expect(the_bundle).to include_gems("ripe_gem 1.0.0")
+    end
+
+    it "summarizes skipped versions at the end of bundle update" do
+      gemfile <<-G
+        source "https://gem.repo3", cooldown: 7
+        gem "ripe_gem"
+      G
+
+      lockfile <<-L
+        GEM
+          remote: https://gem.repo3/
+          specs:
+            ripe_gem (1.0.0)
+
+        PLATFORMS
+          #{lockfile_platforms}
+
+        DEPENDENCIES
+          ripe_gem
+
+        BUNDLED WITH
+           #{Bundler::VERSION}
+      L
+
+      bundle "update ripe_gem", artifice: "compact_index_cooldown"
+
+      expect(out).to include("The following gem versions were skipped by the cooldown setting:")
+      expect(out).to include("* ripe_gem 2.0.0 (available in 6 days), resolved 1.0.0 instead")
+      expect(the_bundle).to include_gems("ripe_gem 1.0.0")
+    end
+
+    it "does not print a skip summary when cooldown is disabled" do
+      gemfile <<-G
+        source "https://gem.repo3"
+        gem "ripe_gem"
+      G
+
+      bundle "install --cooldown 0", artifice: "compact_index_cooldown"
+
+      expect(out).not_to include("skipped by the cooldown setting")
+    end
+
+    it "does not print a skip summary for versions the Gemfile requirement rejects anyway" do
+      gemfile <<-G
+        source "https://gem.repo3"
+        gem "ripe_gem", "~> 1.0"
+      G
+
+      bundle "install --cooldown 7", artifice: "compact_index_cooldown"
+
+      expect(out).not_to include("skipped by the cooldown setting")
+      expect(the_bundle).to include_gems("ripe_gem 1.0.0")
+    end
+
+    it "does not print a skip summary when installing from an up-to-date lockfile" do
+      gemfile <<-G
+        source "https://gem.repo3", cooldown: 7
+        gem "ripe_gem"
+      G
+
+      bundle "install", artifice: "compact_index_cooldown"
+      expect(out).to include("skipped by the cooldown setting")
+
+      bundle "install", artifice: "compact_index_cooldown"
+      expect(out).not_to include("skipped by the cooldown setting")
+    end
+
     it "applies cooldown declared per-source in the Gemfile" do
       gemfile <<-G
         source "https://gem.repo3", cooldown: 7