rubocops/lines: require a comment for skip_clean

Library/Homebrew/rubocops/lines.rb

@@ -84,6 +84,28 @@ def audit_formula(_formula_nodes)
         end
       end
 
+      # Ensure every `skip_clean` is documented with a comment.
+      class SkipCleanCommented < FormulaCop
+        sig { override.params(formula_nodes: FormulaNodes).void }
+        def audit_formula(formula_nodes)
+          return if formula_tap != "homebrew-core"
+          return if (body_node = formula_nodes.body_node).nil?
+
+          # Some formulae call `skip_clean` multiple times, only require a
+          # comment on the first
+          method = find_every_method_call_by_name(body_node, :skip_clean).first
+          return if method.nil?
+
+          method_comment = processed_source.comments.find do |comment|
+            (method.loc.line - comment.loc.line).abs <= 1
+          end
+          return unless method_comment.nil?
+
+          offending_node(method)
+          problem "Formulae in homebrew/core should document why `skip_clean` is needed with a comment."
+        end
+      end
+
       # This cop makes sure that idiomatic `assert_*` statements are used.
       class AssertStatements < FormulaCop
         sig { override.params(formula_nodes: FormulaNodes).void }

Library/Homebrew/test/rubocops/text/skip_clean_commented_spec.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "rubocops/lines"
+
+RSpec.describe RuboCop::Cop::FormulaAudit::SkipCleanCommented do
+  subject(:cop) { described_class.new }
+
+  context "when auditing formulae in homebrew-core" do
+    it "reports an offense when skip_clean does not have a comment" do
+      expect_offense(<<~RUBY, "/homebrew-core/")
+        class Foo < Formula
+          url 'https://brew.sh/foo-1.0.tgz'
+
+          skip_clean "bin"
+          ^^^^^^^^^^^^^^^^ FormulaAudit/SkipCleanCommented: Formulae in homebrew/core should document why `skip_clean` is needed with a comment.
+        end
+      RUBY
+    end
+
+    it "reports a single offense for multiple skip_clean lines" do
+      expect_offense(<<~RUBY, "/homebrew-core/")
+        class Foo < Formula
+          url 'https://brew.sh/foo-1.0.tgz'
+
+          skip_clean "bin"
+          ^^^^^^^^^^^^^^^^ FormulaAudit/SkipCleanCommented: Formulae in homebrew/core should document why `skip_clean` is needed with a comment.
+          skip_clean "libexec/bin"
+        end
+      RUBY
+    end
+
+    it "does not report an offense for a comment" do
+      expect_no_offenses(<<~RUBY, "/homebrew-core/")
+        class Foo < Formula
+          # some reason
+          skip_clean "bin"
+        end
+      RUBY
+    end
+
+    it "does not report an offense for an inline comment" do
+      expect_no_offenses(<<~RUBY, "/homebrew-core/")
+        class Foo < Formula
+          skip_clean "bin" # some reason
+        end
+      RUBY
+    end
+
+    it "does not report an offense for a comment above multiple skip_clean lines" do
+      expect_no_offenses(<<~RUBY, "/homebrew-core/")
+        class Foo < Formula
+          # some reason
+          skip_clean "bin"
+          skip_clean "libexec/bin"
+        end
+      RUBY
+    end
+  end
+
+  context "when auditing formulae not in homebrew-core" do
+    it "does not report an offense" do
+      expect_no_offenses(<<~RUBY)
+        class Foo < Formula
+          skip_clean "bin"
+        end
+      RUBY
+    end
+  end
+end