Gem::Resolver#build_extended_explanation

# File tmp/rubies/ruby-4.1.0-preview1/lib/rubygems/resolver.rb, line 530
def build_extended_explanation(name, constraint)
  unfiltered = @unfiltered_specs[name]
  return if unfiltered.empty?

  filtered = @all_specs[name]
  pkg = package_for(name)

  # A prerelease hint applies when the source would strip prereleases for
  # this constraint (global prerelease flag off and the constraint's range
  # doesn't itself reach into prerelease territory) AND a prerelease of
  # the gem exists somewhere.
  prerelease_gated = !(@set.respond_to?(:prerelease) && @set.prerelease) &&
                     !range_admits_prerelease?(constraint.range)
  has_prerelease_candidate = prerelease_gated &&
                             @all_versions[pkg].any?(&:prerelease?)

  return if filtered.length == unfiltered.length && !has_prerelease_candidate

  hints = []

  # Check for specs that exist for other platforms
  platform_specs = unfiltered.select do |s|
    !Gem::Platform.installable?(s) && constraint.range.include?(s.version)
  end
  if platform_specs.any?
    label = "#{name} (#{constraint.constraint_string})"
    hints << "The source contains the following gems matching '#{label}':"
    platform_specs.each do |s|
      actual = s.respond_to?(:spec) ? s.spec : s
      hints << "  * #{actual.full_name}"
    end
  end

  # Check for specs filtered by Ruby version
  installable = select_local_platforms(unfiltered)
  ruby_specs = installable.select do |s|
    actual = s.respond_to?(:spec) ? s.spec : s
    constraint.range.include?(s.version) &&
      !actual.required_ruby_version.satisfied_by?(Gem.ruby_version)
  rescue StandardError
    false
  end
  if ruby_specs.any?
    versions = ruby_specs.map(&:version).uniq.sort.reverse.first(3)
    sample = ruby_specs.find {|s| s.version == versions.first }
    actual = sample.respond_to?(:spec) ? sample.spec : sample
    ruby_req = actual.required_ruby_version
    hints << "#{name} #{versions.join(", ")} requires Ruby #{ruby_req} (you have #{Gem.ruby_version})"
  end

  # Check for specs filtered by the cooldown period
  if @cooldown&.active?
    cooldown_specs = installable.select do |s|
      constraint.range.include?(s.version) && @cooldown.skip?(s.created_at)
    end
    if cooldown_specs.any?
      versions = cooldown_specs.map(&:version).uniq.sort.reverse.first(3)
      hints << "#{name} #{versions.join(", ")} published within the cooldown period (#{@cooldown.days} days). Use --cooldown 0 to bypass it."
    end
  end

  # Check for specs filtered by prerelease status
  if prerelease_gated
    prerelease_versions = @all_versions[pkg].select(&:prerelease?)
    if prerelease_versions.any?
      versions = prerelease_versions.sort.reverse.first(3) # limit to avoid cluttering error output
      hints << "#{name} #{versions.join(", ")} are pre-release versions. Use --prerelease to allow pre-release gems."
    end
  end

  hints.empty? ? nil : hints.join("\n")
end