MacOSRequirement: add #highest_allowed method

This adds a `#highest_allowed` method to `MacOSRequirement`, so we can
easily identify the highest supported macOS version that a requirement
allows, if any.

This can be used when producing a minimal set of supported macOS
versions that meet requirements in `UsesOnSystem.macos_requirements`.
One of the intended use cases for this is to identify which macOS
versions we could simulate to work with all variations of a cask that
uses macOS on_system blocks.

Library/Homebrew/requirements/macos_requirement.rb

@@ -88,6 +88,16 @@ class MacOSRequirement < Requirement
     end
   end
 
+  # Finds the highest supported {MacOSVersion} that meets the requirement, if
+  # any.
+  sig { returns(T.nilable(MacOSVersion)) }
+  def highest_allowed
+    MacOSVersion::SYMBOLS.each_key do |sym|
+      candidate_version = MacOSVersion.from_symbol(sym)
+      return candidate_version if allows?(candidate_version)
+    end
+  end
+
   def message(type: :formula)
     return "macOS is required for this software." unless version_specified?
 

Library/Homebrew/test/requirements/macos_requirement_spec.rb

@@ -7,6 +7,7 @@ RSpec.describe MacOSRequirement do
 
   let(:macos_oldest_allowed) { MacOSVersion.new(HOMEBREW_MACOS_OLDEST_ALLOWED) }
   let(:macos_newest_allowed) { MacOSVersion.new(HOMEBREW_MACOS_NEWEST_UNSUPPORTED) }
+  let(:macos_newest_supported) { MacOSVersion.new(MacOSVersion::SYMBOLS.values.first) }
   let(:big_sur_major) { MacOSVersion.new("11.0") }
 
   describe "#satisfied?" do
@@ -63,4 +64,19 @@ RSpec.describe MacOSRequirement do
     expect(exact_requirement.allows?(big_sur_major)).to be true
     expect(range_requirement.allows?(big_sur_major)).to be true
   end
+
+  specify "#highest_allowed" do
+    macos_version_sonoma = MacOSVersion.new("14")
+
+    no_requirement = described_class.new
+    max_requirement = described_class.new([:sonoma], comparator: "<=")
+    min_requirement = described_class.new([:sonoma], comparator: ">=")
+    exact_requirement = described_class.new([:sonoma], comparator: "==")
+    range_requirement = described_class.new([[:sonoma, :monterey]], comparator: "==")
+    expect(no_requirement.highest_allowed).to eq macos_newest_supported
+    expect(max_requirement.highest_allowed).to eq macos_version_sonoma
+    expect(min_requirement.highest_allowed).to eq macos_newest_supported
+    expect(exact_requirement.highest_allowed).to eq macos_version_sonoma
+    expect(range_requirement.highest_allowed).to eq macos_version_sonoma
+  end
 end