Print source location when inspecting routes

In larger route files, or when routes are spread across multiple files,
it can be difficult to get from the output of the route inspector to the
relevant route definition.

This commit adds a route source location to the route, and uses that in
the HtmlTableFormatter (for rails/info and the debug exceptions
middleware) and the Expanded formatter (for `rails routes -E`).

To avoid doing extra work in production, it only sets the source location
in development.

This commit injects the application's backtrace cleaner so we can use it
to remove the rails root from the path. This also means we don't get
source locations for the routes defined by Rails.

If mounting an engine from a gem, we'll get a source location for where
we mount it in the application, but not for the routes defined in the
gem itself. That's probably good enough, since Rails already prints
routes for an engine separately under the title "Routes for
Foo::Engine".

Co-authored-by: John Hawthorn <[email protected]>
Co-authored-by: Luan Vieira <[email protected]>
Co-authored-by: Daniel Colson <[email protected]>

Author: 3 people

actionpack/lib/action_dispatch/journey/route.rb

@@ -5,7 +5,7 @@ module ActionDispatch
   module Journey
     class Route
       attr_reader :app, :path, :defaults, :name, :precedence, :constraints,
-                  :internal, :scope_options, :ast
+                  :internal, :scope_options, :ast, :source_location
 
       alias :conditions :constraints
 
@@ -53,7 +53,7 @@ def self.verb_matcher(verb)
       ##
       # +path+ is a path constraint.
       # +constraints+ is a hash of constraints to be applied to this route.
-      def initialize(name:, app: nil, path:, constraints: {}, required_defaults: [], defaults: {}, request_method_match: nil, precedence: 0, scope_options: {}, internal: false)
+      def initialize(name:, app: nil, path:, constraints: {}, required_defaults: [], defaults: {}, request_method_match: nil, precedence: 0, scope_options: {}, internal: false, source_location: nil)
         @name        = name
         @app         = app
         @path        = path
@@ -69,6 +69,7 @@ def initialize(name:, app: nil, path:, constraints: {}, required_defaults: [], d
         @path_formatter    = @path.build_formatter
         @scope_options     = scope_options
         @internal          = internal
+        @source_location   = source_location
 
         @ast = @path.ast.root
         @path.ast.route = self

actionpack/lib/action_dispatch/middleware/templates/routes/_route.html.erb

@@ -13,4 +13,7 @@
   <td>
     <%=simple_format route[:reqs] %>
   </td>
+  <td>
+    <%=simple_format route[:source_location] %>
+  </td>
 </tr>

actionpack/lib/action_dispatch/middleware/templates/routes/_table.html.erb

@@ -90,9 +90,10 @@
       <th class="http-verb">HTTP Verb</th>
       <th>Path</th>
       <th>Controller#Action</th>
+      <th>Source Location</th>
     </tr>
     <tr>
-      <th colspan="4" id="search_container"><%= search_field(:query, nil, id: 'search', placeholder: "Search") %></th>
+      <th colspan="5" id="search_container"><%= search_field(:query, nil, id: 'search', placeholder: "Search") %></th>
     </tr>
   </thead>
   <tbody class='exact_matches' id='exact_matches'>

actionpack/lib/action_dispatch/railtie.rb

@@ -67,6 +67,9 @@ class Railtie < Rails::Railtie # :nodoc:
       config.action_dispatch.always_write_cookie = Rails.env.development? if config.action_dispatch.always_write_cookie.nil?
       ActionDispatch::Cookies::CookieJar.always_write_cookie = config.action_dispatch.always_write_cookie
 
+      ActionDispatch::Routing::Mapper.route_source_locations = Rails.env.development?
+      ActionDispatch::Routing::Mapper.backtrace_cleaner = Rails.backtrace_cleaner
+
       ActionDispatch.test_app = app
     end
   end

actionpack/lib/action_dispatch/routing/inspector.rb

@@ -133,7 +133,8 @@ def collect_routes(routes)
             { name: route.name,
               verb: route.verb,
               path: route.path,
-              reqs: route.reqs }
+              reqs: route.reqs,
+              source_location: route.source_location }
           end
         end
 
@@ -239,13 +240,16 @@ def section(routes)
         private
           def draw_expanded_section(routes)
             routes.map.each_with_index do |r, i|
-              <<~MESSAGE.chomp
+              route_rows = <<~MESSAGE.chomp
                 #{route_header(index: i + 1)}
                 Prefix            | #{r[:name]}
                 Verb              | #{r[:verb]}
                 URI               | #{r[:path]}
                 Controller#Action | #{r[:reqs]}
               MESSAGE
+              source_location = "\nSource Location   | #{r[:source_location]}"
+              route_rows += source_location if r[:source_location].present?
+              route_rows
             end
           end
 

actionpack/lib/action_dispatch/routing/mapper.rb

@@ -12,6 +12,9 @@ module Routing
     class Mapper
       URL_OPTIONS = [:protocol, :subdomain, :domain, :host, :port]
 
+      cattr_accessor :route_source_locations, instance_accessor: false, default: false
+      cattr_accessor :backtrace_cleaner, instance_accessor: false, default: ActiveSupport::BacktraceCleaner.new
+
       class Constraints < Routing::Endpoint # :nodoc:
         attr_reader :app, :constraints
 
@@ -170,7 +173,7 @@ def make_route(name, precedence)
           Journey::Route.new(name: name, app: application, path: path, constraints: conditions,
                              required_defaults: required_defaults, defaults: defaults,
                              request_method_match: request_method, precedence: precedence,
-                             scope_options: scope_options, internal: @internal)
+                             scope_options: scope_options, internal: @internal, source_location: route_source_location)
         end
 
         def application
@@ -356,6 +359,15 @@ def constraints(options, path_params)
           def dispatcher(raise_on_name_error)
             Routing::RouteSet::Dispatcher.new raise_on_name_error
           end
+
+          def route_source_location
+            if Mapper.route_source_locations
+              action_dispatch_dir = File.expand_path("..", __dir__)
+              caller_location = caller_locations.find { |location| !location.path.include?(action_dispatch_dir) }
+              cleaned_path = Mapper.backtrace_cleaner.clean([caller_location.path]).first
+              "#{cleaned_path}:#{caller_location.lineno}" if cleaned_path
+            end
+          end
       end
 
       # Invokes Journey::Router::Utils.normalize_path, then ensures that

actionpack/test/dispatch/routing/inspector_test.rb

@@ -317,11 +317,14 @@ def test_routes_can_be_filtered
       end
 
       def test_routes_when_expanded
+        ActionDispatch::Routing::Mapper.route_source_locations = true
         engine = Class.new(Rails::Engine) do
           def self.inspect
             "Blog::Engine"
           end
         end
+        file_name = ActiveSupport::BacktraceCleaner.new.clean([__FILE__]).first
+        lineno = __LINE__
         engine.routes.draw do
           get "/cart", to: "cart#show"
         end
@@ -332,28 +335,36 @@ def self.inspect
           mount engine => "/blog", :as => "blog"
         end
 
-        assert_equal ["--[ Route 1 ]----------",
-                      "Prefix            | custom_assets",
-                      "Verb              | GET",
-                      "URI               | /custom/assets(.:format)",
-                      "Controller#Action | custom_assets#show",
-                      "--[ Route 2 ]----------",
-                      "Prefix            | custom_furnitures",
-                      "Verb              | GET",
-                      "URI               | /custom/furnitures(.:format)",
-                      "Controller#Action | custom_furnitures#show",
-                      "--[ Route 3 ]----------",
-                      "Prefix            | blog",
-                      "Verb              | ",
-                      "URI               | /blog",
-                      "Controller#Action | Blog::Engine",
-                      "",
-                      "[ Routes for Blog::Engine ]",
-                      "--[ Route 1 ]----------",
-                      "Prefix            | cart",
-                      "Verb              | GET",
-                      "URI               | /cart(.:format)",
-                      "Controller#Action | cart#show"], output
+        expected = ["--[ Route 1 ]----------",
+                     "Prefix            | custom_assets",
+                     "Verb              | GET",
+                     "URI               | /custom/assets(.:format)",
+                     "Controller#Action | custom_assets#show",
+                     "Source Location   | #{file_name}:#{lineno + 6}",
+                     "--[ Route 2 ]----------",
+                     "Prefix            | custom_furnitures",
+                     "Verb              | GET",
+                     "URI               | /custom/furnitures(.:format)",
+                     "Controller#Action | custom_furnitures#show",
+                     "Source Location   | #{file_name}:#{lineno + 7}",
+                     "--[ Route 3 ]----------",
+                     "Prefix            | blog",
+                     "Verb              | ",
+                     "URI               | /blog",
+                     "Controller#Action | Blog::Engine",
+                     "Source Location   | #{file_name}:#{lineno + 8}",
+                     "",
+                     "[ Routes for Blog::Engine ]",
+                     "--[ Route 1 ]----------",
+                     "Prefix            | cart",
+                     "Verb              | GET",
+                     "URI               | /cart(.:format)",
+                     "Controller#Action | cart#show",
+                     "Source Location   | #{file_name}:#{lineno + 2}"]
+
+        assert_equal expected, output
+      ensure
+        ActionDispatch::Routing::Mapper.route_source_locations = false
       end
 
       def test_no_routes_matched_filter_when_expanded