Deprecate STATS_DIRECTORIES in favor of CodeStatistics.add_directory

`STATS_DIRECTORIES` is used by third parties to add directories to the
statistics output. It's a global constant defined in a Rake file, that
gets loaded anytime the Rake commands get loaded.

For example Rspec Rails adds these in a prepended Rake task:
https://github.com/rspec/rspec-rails/blob/8c17b4e5020a4d264e8a79e294c58b5c1ef2b005/lib/rspec/rails/tasks/rspec.rake#L43

Rake tasks only get loaded if no matching Thor task has been found. This
means `STATS_DIRECTORIES` is only available when the Rake commands have
loaded.

As the stats command has now been moved to a Thor task, calling
`bin/rails stats` will no longer add directories to `STATS_DIRECTORIES`,
as the Rake commands don't get loaded anymore.

To remove the dependency on Rake and avoid a global constant we can add
an API to add directories: `CodeStatistics.add_directory`.
`STATS_DIRECTORIES` is deprecated.

`deprecate_constant` couldn't be used here as that doesn't seem to work
for the root namespace.

Co-authored-by: Earlopain <[email protected]>

Author: p8

railties/CHANGELOG.md

@@ -1,3 +1,17 @@
+*   Deprecate `::STATS_DIRECTORIES`.
+
+    The global constant `STATS_DIRECTORIES` has been deprecated in favor of
+    `CodeStatistics.add_directory`.
+
+    Add extra directories with `CodeStatistics.add_directory(label, path)`:
+
+    ```ruby
+    require "rails/code_statistics"
+    CodeStatistics.add_directory('My Directory', 'path/to/dir')
+    ```
+
+    *Petrik de Heus*
+
 *   Enable query log tags by default on development env
 
     This can be used to trace troublesome SQL statements back to the application

railties/lib/rails/code_statistics.rb

@@ -3,7 +3,32 @@
 require "rails/code_statistics_calculator"
 require "active_support/core_ext/enumerable"
 
-class CodeStatistics # :nodoc:
+class CodeStatistics
+  DIRECTORIES = [
+    %w(Controllers        app/controllers),
+    %w(Helpers            app/helpers),
+    %w(Jobs               app/jobs),
+    %w(Models             app/models),
+    %w(Mailers            app/mailers),
+    %w(Mailboxes          app/mailboxes),
+    %w(Channels           app/channels),
+    %w(Views              app/views),
+    %w(JavaScripts        app/assets/javascripts),
+    %w(Stylesheets        app/assets/stylesheets),
+    %w(JavaScript         app/javascript),
+    %w(Libraries          lib/),
+    %w(APIs               app/apis),
+    %w(Controller\ tests  test/controllers),
+    %w(Helper\ tests      test/helpers),
+    %w(Job\ tests         test/jobs),
+    %w(Model\ tests       test/models),
+    %w(Mailer\ tests      test/mailers),
+    %w(Mailbox\ tests     test/mailboxes),
+    %w(Channel\ tests     test/channels),
+    %w(Integration\ tests test/integration),
+    %w(System\ tests      test/system),
+  ]
+
   TEST_TYPES = ["Controller tests",
                 "Helper tests",
                 "Model tests",
@@ -16,6 +41,15 @@ class CodeStatistics # :nodoc:
 
   HEADERS = { lines: " Lines", code_lines: "   LOC", classes: "Classes", methods: "Methods" }
 
+  class_attribute :directories, default: DIRECTORIES
+
+  # Add directories to the output of the `bin/rails stats` command.
+  #
+  #   CodeStatistics.add_directory("My Directory", "path/to/dir")
+  def self.add_directory(label, path)
+    self.directories << [label, path]
+  end
+
   def initialize(*pairs)
     @pairs      = pairs
     @statistics = calculate_statistics

railties/lib/rails/commands/stats/stats_command.rb

@@ -1,41 +1,14 @@
 # frozen_string_literal: true
 
-# While global constants are bad, many 3rd party tools depend on this one (e.g
-# rspec-rails & cucumber-rails). So a deprecation warning is needed if we want
-# to remove it.
-STATS_DIRECTORIES ||= [
-  %w(Controllers        app/controllers),
-  %w(Helpers            app/helpers),
-  %w(Jobs               app/jobs),
-  %w(Models             app/models),
-  %w(Mailers            app/mailers),
-  %w(Mailboxes          app/mailboxes),
-  %w(Channels           app/channels),
-  %w(Views              app/views),
-  %w(JavaScripts        app/assets/javascripts),
-  %w(Stylesheets        app/assets/stylesheets),
-  %w(JavaScript         app/javascript),
-  %w(Libraries          lib/),
-  %w(APIs               app/apis),
-  %w(Controller\ tests  test/controllers),
-  %w(Helper\ tests      test/helpers),
-  %w(Job\ tests         test/jobs),
-  %w(Model\ tests       test/models),
-  %w(Mailer\ tests      test/mailers),
-  %w(Mailbox\ tests     test/mailboxes),
-  %w(Channel\ tests     test/channels),
-  %w(Integration\ tests test/integration),
-  %w(System\ tests      test/system),
-]
-
 module Rails
   module Command
     class StatsCommand < Base # :nodoc:
       desc "stats", "Report code statistics (KLOCs, etc) from the application or engine"
       def perform
         require "rails/code_statistics"
+        boot_application!
 
-        stat_directories = STATS_DIRECTORIES.collect do |name, dir|
+        stat_directories = CodeStatistics.directories.map do |name, dir|
           [name, Rails::Command.application_root.join(dir)]
         end.select { |name, dir| File.directory?(dir) }
 

railties/lib/rails/tasks/statistics.rake

@@ -1,32 +1,11 @@
 # frozen_string_literal: true
 
-# While global constants are bad, many 3rd party tools depend on this one (e.g
-# rspec-rails & cucumber-rails). So a deprecation warning is needed if we want
-# to remove it.
-STATS_DIRECTORIES ||= [
-  %w(Controllers        app/controllers),
-  %w(Helpers            app/helpers),
-  %w(Jobs               app/jobs),
-  %w(Models             app/models),
-  %w(Mailers            app/mailers),
-  %w(Mailboxes          app/mailboxes),
-  %w(Channels           app/channels),
-  %w(Views              app/views),
-  %w(JavaScripts        app/assets/javascripts),
-  %w(Stylesheets        app/assets/stylesheets),
-  %w(JavaScript         app/javascript),
-  %w(Libraries          lib/),
-  %w(APIs               app/apis),
-  %w(Controller\ tests  test/controllers),
-  %w(Helper\ tests      test/helpers),
-  %w(Job\ tests         test/jobs),
-  %w(Model\ tests       test/models),
-  %w(Mailer\ tests      test/mailers),
-  %w(Mailbox\ tests     test/mailboxes),
-  %w(Channel\ tests     test/channels),
-  %w(Integration\ tests test/integration),
-  %w(System\ tests      test/system),
-]
+require "rails/code_statistics"
+STATS_DIRECTORIES = ActiveSupport::Deprecation::DeprecatedObjectProxy.new(
+  CodeStatistics::DIRECTORIES,
+  "`STATS_DIRECTORIES` is deprecated and will be removed in Rails 8.1! Use `CodeStatistics.add_directory('My Directory', 'path/to/dir)` instead.",
+  Rails.deprecator
+)
 
 desc "Report code statistics (KLOCs, etc) from the application or engine"
 task :stats do

railties/test/commands/stats_test.rb

@@ -8,12 +8,25 @@ class Rails::Command::StatsTest < ActiveSupport::TestCase
   setup :build_app
   teardown :teardown_app
 
+  test "`bin/rails stats` handles directories added by third parties" do
+    app_dir "custom/dir"
+
+    app_file "config/initializers/custom.rb", <<~CODE
+      require "rails/code_statistics"
+      CodeStatistics.add_directory("Custom dir", "custom/dir")
+    CODE
+
+    output = rails "stats"
+    assert_match "Custom dir", output
+  end
+
   test "`bin/rails stats` handles non-existing directories added by third parties" do
     app_file "config/initializers/custom.rb", <<~CODE
       require "rails/code_statistics"
-      ::STATS_DIRECTORIES << ["Non\ Existing", "app/non_existing"]
+      CodeStatistics.add_directory("Non Existing", "app/non_existing")
     CODE
 
-    assert rails "stats"
+    output = rails "stats"
+    assert_no_match "Non Existing", output
   end
 end