Include the missing dependency's version in resolver errors & test and document Bundler-aligned resolver behaviors

Author: colby-swandale

lib/rubygems/resolver.rb

@@ -127,7 +127,14 @@ def initialize(needed, set = nil)
   # Proceed with resolution! Returns an array of ActivationRequest objects.
 
   def resolve
-    # Pre-check: raise UnsatisfiableDependencyError for root deps with no matches
+    # Pre-check: raise UnsatisfiableDependencyError for root deps with no
+    # platform match. We filter by platform ONLY here (not required_ruby_version
+    # / required_rubygems_version): a foreign-platform gem is genuinely "not
+    # found", but a gem that exists yet is incompatible with the running Ruby
+    # should flow through the solver to a DependencyResolutionError that names
+    # the Ruby requirement. That matches Bundler (which models Ruby as a
+    # synthetic dependency, so this surfaces as a solve failure) and gives a
+    # clearer message than the platform-oriented UnsatisfiableDependencyError.
     @needed.each do |dep|
       next if @soft_missing
       dep_request = DependencyRequest.new(dep, nil)
@@ -175,6 +182,21 @@ def all_versions_for(package)
     name = package.to_s
 
     if (skip_dep_gems = skip_gems[name]) && !skip_dep_gems.empty?
+      # Conservative mode: float the already-installed (skip) versions to the
+      # front so the solver prefers them. This sets *preference* only (it feeds
+      # the strategy's version-index map); it does not restrict availability, so
+      # every version stays selectable via versions_for. When an installed
+      # version is made impossible by a downstream conflict, the solver
+      # backtracks to a newer version instead of failing. Molinillo instead
+      # hard-restricted the candidate set to skip versions and raised.
+      #
+      # This reaches the same outcome as Bundler (upgrade-over-raise) for the
+      # common single-blocked-gem case, though the mechanism differs: Bundler
+      # hard-pins locked gems and selectively unlocks + re-solves on conflict,
+      # whereas we float as a preference and let PubGrub backtrack in one solve.
+      # The float can therefore over-upgrade when several installed gems are
+      # jointly involved in a conflict; that outcome-level divergence is
+      # accepted (see test_conservative_upgrades_when_installed_blocked).
       skip_versions = skip_dep_gems.map(&:version)
       preferred, rest = versions.partition {|v| skip_versions.include?(v) }
       preferred + rest
@@ -270,9 +292,16 @@ def incompatibilities_for(package, version)
       # self_constraint lets clean sibling versions still resolve via backtracking.
       if @unfiltered_specs[dep_package_name].empty?
         cause = Gem::PubGrub::Incompatibility::InvalidDependency.new(dep_package, dep_constraint)
+        self_term = Gem::PubGrub::Term.new(self_constraint, true)
+        # PubGrub's default InvalidDependency rendering drops the version
+        # requirement ("depends on unknown package bar"). Supply a custom
+        # explanation so the missing dependency's constraint is preserved
+        # ("depends on bar = 0.5 which could not be found in any repository"),
+        # matching Molinillo's diagnostics.
         return [Gem::PubGrub::Incompatibility.new(
-          [Gem::PubGrub::Term.new(self_constraint, true)],
-          cause: cause
+          [self_term],
+          cause: cause,
+          custom_explanation: "#{self_term.to_s(allow_every: true)} depends on #{dep_constraint} which could not be found in any repository"
         )]
       end
 

test/rubygems/test_gem_dependency_installer.rb

@@ -817,7 +817,7 @@ def test_install_domain_local
         inst.install "b"
       end
 
-      assert_match(/depends on unknown package a/, e.message)
+      assert_match(/depends on a >= 0 which could not be found in any repository/, e.message)
     end
 
     assert_equal [], inst.installed_gems.map(&:full_name)

test/rubygems/test_gem_resolver.rb

@@ -140,6 +140,34 @@ def test_resolve_conservative
     assert_resolves_to [a2_spec, b2_spec, c1_spec, d2_spec, e1_spec], res
   end
 
+  def test_conservative_upgrades_when_installed_blocked
+    # Conservative mode floats the installed (skip) version to the front but
+    # keeps newer versions selectable. When the installed version cannot be
+    # used because its own dependency is unsatisfiable, the solver backtracks
+    # to a newer version instead of failing. This intentionally diverges from
+    # Molinillo (which hard-restricted to skip versions and raised) and reaches
+    # Bundler's upgrade-over-raise outcome. See the comment in
+    # Gem::Resolver#all_versions_for.
+    a1_spec = util_spec "a", 1 do |s|
+      s.add_dependency "b", ">= 2"
+    end
+    a2_spec = util_spec "a", 2 do |s|
+      s.add_dependency "b", ">= 1"
+    end
+    b1_spec = util_spec "b", 1
+
+    # b-2 is intentionally absent, so a-1's `b >= 2` cannot be satisfied.
+    deps = [make_dep("a", ">= 1")]
+    s = set a1_spec, a2_spec, b1_spec
+
+    res = Gem::Resolver.new deps, s
+    # a-1 is already installed and satisfies `a >= 1`, so conservative mode
+    # prefers it - but it is blocked by the missing b-2, forcing an upgrade.
+    res.skip_gems = { "a" => [a1_spec] }
+
+    assert_resolves_to [a2_spec, b1_spec], res
+  end
+
   def test_resolve_development
     a_spec = util_spec "a", 1 do |s|
       s.add_development_dependency "b"
@@ -516,7 +544,7 @@ def test_raises_and_reports_an_implicit_request_properly
       r.resolve
     end
 
-    assert_match(/depends on unknown package b/, e.message)
+    assert_match(/depends on b = 2 which could not be found in any repository/, e.message)
   end
 
   def test_raises_when_possibles_are_exhausted
@@ -945,6 +973,28 @@ def test_error_includes_ruby_version_hint_when_filtered
     assert_match(/you have/, e.message)
   end
 
+  def test_root_gem_incompatible_ruby_version_names_ruby_requirement
+    # A requested (root) gem available only for an incompatible Ruby version
+    # flows through the solver to a DependencyResolutionError whose message
+    # names the Ruby requirement. This matches Bundler (which models Ruby as a
+    # synthetic dependency and reports a solve failure) and is clearer than the
+    # platform-oriented UnsatisfiableDependencyError. Contrast the foreign-
+    # *platform* case (test_raises_and_explains_when_platform_prevents_install),
+    # which is genuinely "not found" and does raise UnsatisfiableDependencyError.
+    a = util_spec "a", "1.0" do |s|
+      s.required_ruby_version = ">= 999.0"
+    end
+
+    ad = make_dep "a", "= 1.0"
+    r = Gem::Resolver.new([ad], set(a))
+
+    e = assert_raise Gem::DependencyResolutionError do
+      r.resolve
+    end
+
+    assert_match(/requires Ruby >= 999.0/, e.message)
+  end
+
   def test_self_dependency_does_not_crash
     a = util_spec "a", "1.0" do |s|
       s.add_dependency "a"
@@ -1090,7 +1140,7 @@ def test_fails_when_every_version_depends_on_missing_package
       r.resolve
     end
 
-    assert_match(/every version of a depends on unknown package zzz/, e.message)
+    assert_match(/every version of a depends on zzz >= 1 which could not be found in any repository/, e.message)
   end
 
   def test_resolves_when_only_lowest_version_has_missing_dep