Merge pull request rails#55230 from rails/fxn/first_clean_location

Implement ActiveSupport::BacktraceCleaner#first_clean_location

Author: fxn

activesupport/CHANGELOG.md

@@ -1,10 +1,18 @@
+*   The new method `ActiveSupport::BacktraceCleaner#first_clean_location`
+    returns the first clean location of the caller's call stack, or `nil`.
+    Locations are `Thread::Backtrace::Location` objects. Useful when you want to
+    report the application-level location where something happened as an object.
+
+    *Xavier Noria*
+
 *   FileUpdateChecker and EventedFileUpdateChecker ignore changes in Gem.path now.
 
     *Ermolaev Andrey*, *zzak*
 
 *   The new method `ActiveSupport::BacktraceCleaner#first_clean_frame` returns
     the first clean frame of the caller's backtrace, or `nil`. Useful when you
-    want to report the application-level location where something happened.
+    want to report the application-level frame where something happened as a
+    string.
 
     *Xavier Noria*
 

activesupport/lib/active_support/backtrace_cleaner.rb

@@ -77,6 +77,8 @@ def clean_frame(frame, kind = :silent)
     # Thread.each_caller_location does not accept a start in Ruby < 3.4.
     if Thread.method(:each_caller_location).arity == 0
       # Returns the first clean frame of the caller's backtrace, or +nil+.
+      #
+      # Frames are strings.
       def first_clean_frame(kind = :silent)
         caller_location_skipped = false
 
@@ -92,6 +94,8 @@ def first_clean_frame(kind = :silent)
       end
     else
       # Returns the first clean frame of the caller's backtrace, or +nil+.
+      #
+      # Frames are strings.
       def first_clean_frame(kind = :silent)
         Thread.each_caller_location(2) do |location|
           frame = clean_frame(location, kind)
@@ -100,6 +104,34 @@ def first_clean_frame(kind = :silent)
       end
     end
 
+    # Thread.each_caller_location does not accept a start in Ruby < 3.4.
+    if Thread.method(:each_caller_location).arity == 0
+      # Returns the first clean location of the caller's call stack, or +nil+.
+      #
+      # Locations are Thread::Backtrace::Location objects.
+      def first_clean_location(kind = :silent)
+        caller_location_skipped = false
+
+        Thread.each_caller_location do |location|
+          unless caller_location_skipped
+            caller_location_skipped = true
+            next
+          end
+
+          return location if clean_frame(location, kind)
+        end
+      end
+    else
+      # Returns the first clean location of the caller's call stack, or +nil+.
+      #
+      # Locations are Thread::Backtrace::Location objects.
+      def first_clean_location(kind = :silent)
+        Thread.each_caller_location(2) do |location|
+          return location if clean_frame(location, kind)
+        end
+      end
+    end
+
     # Adds a filter from the block provided. Each line in the backtrace will be
     # mapped against this filter.
     #

activesupport/test/backtrace_cleaner_test.rb

@@ -137,7 +137,7 @@ def setup
   end
 end
 
-class BacktraceCleanerFirstCleanFrame < ActiveSupport::TestCase
+class BacktraceCleanerFirstCleanFrameTest < ActiveSupport::TestCase
   def setup
     @bc = ActiveSupport::BacktraceCleaner.new
   end
@@ -180,3 +180,55 @@ def invoke_first_clean_frame(kind = :silent)
     assert_nil invoke_first_clean_frame_defaults
   end
 end
+
+class BacktraceCleanerFirstCleanLocationTest < ActiveSupport::TestCase
+  def setup
+    @bc = ActiveSupport::BacktraceCleaner.new
+  end
+
+  def invoke_first_clean_location_defaults
+    -> do
+      @bc.first_clean_location.tap { @line = __LINE__ + 1 }
+    end.call
+  end
+
+  def invoke_first_clean_location(kind = :silent)
+    -> do
+      @bc.first_clean_location(kind).tap { @line = __LINE__ + 1 }
+    end.call
+  end
+
+  test "returns the first clean location (defaults)" do
+    location = invoke_first_clean_location_defaults
+
+    assert_equal __FILE__, location.path
+    assert_equal @line, location.lineno
+  end
+
+  test "returns the first clean location (:silent)" do
+    location = invoke_first_clean_location(:silent)
+
+    assert_equal __FILE__, location.path
+    assert_equal @line, location.lineno
+  end
+
+  test "returns the first clean location (:noise)" do
+    @bc.add_silencer { true }
+    location = invoke_first_clean_location(:noise)
+
+    assert_equal __FILE__, location.path
+    assert_equal @line, location.lineno
+  end
+
+  test "returns the first clean location (:any)" do
+    location = invoke_first_clean_location(:any) # fallback of the case statement
+
+    assert_equal __FILE__, location.path
+    assert_equal @line, location.lineno
+  end
+
+  test "returns nil if there is no clean location" do
+    @bc.add_silencer { true }
+    assert_nil invoke_first_clean_location_defaults
+  end
+end