audit: check versioned formulae for keg_only :versioned_formula

Library/Homebrew/dev-cmd/audit.rb

@@ -525,6 +525,25 @@ module Homebrew
       problem "keg_only reason should not end with a period."
     end
 
+    def audit_versioned_keg_only
+      return unless formula.versioned_formula?
+      return unless @core_tap
+
+      return if formula.keg_only? && formula.keg_only_reason.reason == :versioned_formula
+
+      keg_only_whitelist = %w[
+        autoconf@2.13
+        bash-completion@2
+        gnupg@1.4
+        lua@5.1
+        python@2
+      ].freeze
+
+      return if keg_only_whitelist.include?(formula.name) || formula.name.start_with?("gcc@")
+
+      problem "Versioned formulae should use `keg_only :versioned_formula`"
+    end
+
     def audit_homepage
       homepage = formula.homepage
 

Library/Homebrew/test/dev-cmd/audit_spec.rb

@@ -600,5 +600,49 @@ module Homebrew
         expect(fa.problems).to eq([])
       end
     end
+
+    describe "#audit_versioned_keg_only" do
+      specify "it warns when a versioned formula is not `keg_only`" do
+        fa = formula_auditor "foo@1.1", <<~RUBY, core_tap: true
+          class FooAT11 < Formula
+            url "https://example.com/foo-1.1.tgz"
+          end
+        RUBY
+
+        fa.audit_versioned_keg_only
+
+        expect(fa.problems.first)
+          .to match("Versioned formulae should use `keg_only :versioned_formula`")
+      end
+
+      specify "it warns when a versioned formula has an incorrect `keg_only` reason" do
+        fa = formula_auditor "foo@1.1", <<~RUBY, core_tap: true
+          class FooAT11 < Formula
+            url "https://example.com/foo-1.1.tgz"
+
+            keg_only :provided_by_macos
+          end
+        RUBY
+
+        fa.audit_versioned_keg_only
+
+        expect(fa.problems.first)
+          .to match("Versioned formulae should use `keg_only :versioned_formula`")
+      end
+
+      specify "it does not warn when a versioned formula has `keg_only :versioned_formula`" do
+        fa = formula_auditor "foo@1.1", <<~RUBY, core_tap: true
+          class FooAT11 < Formula
+            url "https://example.com/foo-1.1.tgz"
+
+            keg_only :versioned_formula
+          end
+        RUBY
+
+        fa.audit_versioned_keg_only
+
+        expect(fa.problems).to eq([])
+      end
+    end
   end
 end