Merge pull request #33220 from anniecodes/notes-command

Adds `Rails::Command::NotesCommand` and makes `rake notes` use it under the hood

4 files changed, 184 insertions, 18 deletions

diff --git a/railties/lib/rails/commands/notes/notes_command.rb b/railties/lib/rails/commands/notes/notes_command.rb
new file mode 100644
index 0000000000..a0faaeff8f
--- /dev/null
+++ b/railties/lib/rails/commands/notes/notes_command.rb
@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/source_annotation_extractor"
+
+module Rails
+  module Command
+    class NotesCommand < Base # :nodoc:
+      class_option :annotations, aliases: "-a", desc: "Filter by specific annotations, e.g. Foobar TODO", type: :array, default: %w(OPTIMIZE FIXME TODO)
+
+      def perform(*)
+        require_application_and_environment!
+
+        deprecation_warning
+        display_annotations
+      end
+
+      private
+        def display_annotations
+          annotations = options[:annotations]
+          tag = (annotations.length > 1)
+
+          Rails::SourceAnnotationExtractor.enumerate annotations.join("|"), tag: tag, dirs: directories
+        end
+
+        def directories
+          Rails::SourceAnnotationExtractor::Annotation.directories + source_annotation_directories
+        end
+
+        def deprecation_warning
+          return if source_annotation_directories.empty?
+          ActiveSupport::Deprecation.warn("`SOURCE_ANNOTATION_DIRECTORIES` will be deprecated in Rails 6.1. You can add default directories by using config.annotations.register_directories instead.")
+        end
+
+        def source_annotation_directories
+          ENV["SOURCE_ANNOTATION_DIRECTORIES"].to_s.split(",")
+        end
+    end
+  end
+end
diff --git a/railties/lib/rails/source_annotation_extractor.rb b/railties/lib/rails/source_annotation_extractor.rb
index 7257aaeaae..2d66a4dc7d 100644
--- a/railties/lib/rails/source_annotation_extractor.rb
+++ b/railties/lib/rails/source_annotation_extractor.rb
@@ -8,12 +8,7 @@ SourceAnnotationExtractor = ActiveSupport::Deprecation::DeprecatedConstantProxy.
   new("SourceAnnotationExtractor", "Rails::SourceAnnotationExtractor")
 
 module Rails
-  # Implements the logic behind the rake tasks for annotations like
-  #
-  #   rails notes
-  #   rails notes:optimize
-  #
-  # and friends. See <tt>rails -T notes</tt> and <tt>railties/lib/rails/tasks/annotations.rake</tt>.
+  # Implements the logic behind <tt>Rails::Command::NotesCommand</tt>. See <tt>rails notes --help</tt> for usage information.
   #
   # Annotation objects are triplets <tt>:line</tt>, <tt>:tag</tt>, <tt>:text</tt> that
   # represent the line where the annotation lives, its tag, and its text. Note
@@ -25,7 +20,7 @@ module Rails
   class SourceAnnotationExtractor
     class Annotation < Struct.new(:line, :tag, :text)
       def self.directories
-        @@directories ||= %w(app config db lib test) + (ENV["SOURCE_ANNOTATION_DIRECTORIES"] || "").split(",")
+        @@directories ||= %w(app config db lib test)
       end
 
       # Registers additional directories to be included
@@ -59,15 +54,19 @@ module Rails
         s << "[#{tag}] " if options[:tag]
         s << text
       end
+
+      # Used in annotations.rake
+      #:nodoc:
+      def self.notes_task_deprecation_warning
+        ActiveSupport::Deprecation.warn("This rake task is deprecated and will be removed in Rails 6.1. \nRefer to `rails notes --help` for more information.\n")
+        puts "\n"
+      end
     end
 
     # Prints all annotations with tag +tag+ under the root directories +app+,
     # +config+, +db+, +lib+, and +test+ (recursively).
     #
-    # Additional directories may be added using a comma-delimited list set using
-    # <tt>ENV['SOURCE_ANNOTATION_DIRECTORIES']</tt>.
-    #
-    # Directories may also be explicitly set using the <tt>:dirs</tt> key in +options+.
+    # Specific directories can be explicitly set using the <tt>:dirs</tt> key in +options+.
     #
     #   Rails::SourceAnnotationExtractor.enumerate 'TODO|FIXME', dirs: %w(app lib), tag: true
     #
@@ -75,7 +74,7 @@ module Rails
     #
     # See <tt>#find_in</tt> for a list of file extensions that will be taken into account.
     #
-    # This class method is the single entry point for the rake tasks.
+    # This class method is the single entry point for the `rails notes` command.
     def self.enumerate(tag, options = {})
       extractor = new(tag)
       dirs = options.delete(:dirs) || Annotation.directories
diff --git a/railties/lib/rails/tasks/annotations.rake b/railties/lib/rails/tasks/annotations.rake
index 60bcdc5e1b..65af778a15 100644
--- a/railties/lib/rails/tasks/annotations.rake
+++ b/railties/lib/rails/tasks/annotations.rake
@@ -2,21 +2,21 @@
 
 require "rails/source_annotation_extractor"
 
-desc "Enumerate all annotations (use notes:optimize, :fixme, :todo for focus)"
 task :notes do
-  Rails::SourceAnnotationExtractor.enumerate "OPTIMIZE|FIXME|TODO", tag: true
+  Rails::SourceAnnotationExtractor::Annotation.notes_task_deprecation_warning
+  Rails::Command.invoke :notes
 end
 
 namespace :notes do
   ["OPTIMIZE", "FIXME", "TODO"].each do |annotation|
-    # desc "Enumerate all #{annotation} annotations"
     task annotation.downcase.intern do
-      Rails::SourceAnnotationExtractor.enumerate annotation
+      Rails::SourceAnnotationExtractor::Annotation.notes_task_deprecation_warning
+      Rails::Command.invoke :notes, ["--annotations", annotation]
     end
   end
 
-  desc "Enumerate a custom annotation, specify with ANNOTATION=CUSTOM"
   task :custom do
-    Rails::SourceAnnotationExtractor.enumerate ENV["ANNOTATION"]
+    Rails::SourceAnnotationExtractor::Annotation.notes_task_deprecation_warning
+    Rails::Command.invoke :notes, ["--annotations", ENV["ANNOTATION"]]
   end
 end
diff --git a/railties/test/commands/notes_test.rb b/railties/test/commands/notes_test.rb
new file mode 100644
index 0000000000..d8647b3aca
--- /dev/null
+++ b/railties/test/commands/notes_test.rb
@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "isolation/abstract_unit"
+require "rails/command"
+require "rails/commands/notes/notes_command"
+
+class Rails::Command::NotesTest < ActiveSupport::TestCase
+  setup :build_app
+  teardown :teardown_app
+
+  test "`rails notes` displays results for default directories and default annotations" do
+    app_file "app/controllers/some_controller.rb", "# OPTIMIZE: note in app directory"
+    app_file "config/initializers/some_initializer.rb", "# TODO: note in config directory"
+    app_file "db/some_seeds.rb", "# FIXME: note in db directory"
+    app_file "lib/some_file.rb", "# TODO: note in lib directory"
+    app_file "test/some_test.rb", 1000.times.map { "" }.join("\n") << "# FIXME: note in test directory"
+
+    app_file "some_other_dir/blah.rb", "# TODO: note in some_other directory"
+
+    assert_equal <<~OUTPUT, run_notes_command
+      app/controllers/some_controller.rb:
+        * [   1] [OPTIMIZE] note in app directory
+
+      config/initializers/some_initializer.rb:
+        * [   1] [TODO] note in config directory
+
+      db/some_seeds.rb:
+        * [   1] [FIXME] note in db directory
+
+      lib/some_file.rb:
+        * [   1] [TODO] note in lib directory
+
+      test/some_test.rb:
+        * [1000] [FIXME] note in test directory
+
+    OUTPUT
+  end
+
+  test "`rails notes` displays an empty array when no results were found" do
+    assert_equal "", run_notes_command
+  end
+
+  test "`rails notes --annotations` displays results for a single annotation without being prefixed by a tag" do
+    app_file "db/some_seeds.rb", "# FIXME: note in db directory"
+    app_file "test/some_test.rb", 1000.times.map { "" }.join("\n") << "# FIXME: note in test directory"
+
+    app_file "app/controllers/some_controller.rb", "# OPTIMIZE: note in app directory"
+    app_file "config/initializers/some_initializer.rb", "# TODO: note in config directory"
+
+    assert_equal <<~OUTPUT, run_notes_command(["--annotations", "FIXME"])
+      db/some_seeds.rb:
+        * [   1] note in db directory
+
+      test/some_test.rb:
+        * [1000] note in test directory
+
+    OUTPUT
+  end
+
+  test "`rails notes --annotations` displays results for multiple annotations being prefixed by a tag" do
+    app_file "app/controllers/some_controller.rb", "# FOOBAR: note in app directory"
+    app_file "config/initializers/some_initializer.rb", "# TODO: note in config directory"
+    app_file "lib/some_file.rb", "# TODO: note in lib directory"
+
+    app_file "test/some_test.rb", 1000.times.map { "" }.join("\n") << "# FIXME: note in test directory"
+
+    assert_equal <<~OUTPUT, run_notes_command(["--annotations", "FOOBAR", "TODO"])
+      app/controllers/some_controller.rb:
+        * [1] [FOOBAR] note in app directory
+
+      config/initializers/some_initializer.rb:
+        * [1] [TODO] note in config directory
+
+      lib/some_file.rb:
+        * [1] [TODO] note in lib directory
+
+    OUTPUT
+  end
+
+  test "displays results from additional directories added to the default directories from a config file" do
+    app_file "db/some_seeds.rb", "# FIXME: note in db directory"
+    app_file "lib/some_file.rb", "# TODO: note in lib directory"
+    app_file "spec/spec_helper.rb", "# TODO: note in spec"
+    app_file "spec/models/user_spec.rb", "# TODO: note in model spec"
+
+    add_to_config "config.annotations.register_directories \"spec\""
+
+    assert_equal <<~OUTPUT, run_notes_command
+      db/some_seeds.rb:
+        * [1] [FIXME] note in db directory
+
+      lib/some_file.rb:
+        * [1] [TODO] note in lib directory
+
+      spec/models/user_spec.rb:
+        * [1] [TODO] note in model spec
+
+      spec/spec_helper.rb:
+        * [1] [TODO] note in spec
+
+    OUTPUT
+  end
+
+  test "displays results from additional file extensions added to the default extensions from a config file" do
+    add_to_config "config.assets.precompile = []"
+    add_to_config %q{ config.annotations.register_extensions("scss", "sass") { |annotation| /\/\/\s*(#{annotation}):?\s*(.*)$/ } }
+    app_file "db/some_seeds.rb", "# FIXME: note in db directory"
+    app_file "app/assets/stylesheets/application.css.scss", "// TODO: note in scss"
+    app_file "app/assets/stylesheets/application.css.sass", "// TODO: note in sass"
+
+    assert_equal <<~OUTPUT, run_notes_command
+      app/assets/stylesheets/application.css.sass:
+        * [1] [TODO] note in sass
+
+      app/assets/stylesheets/application.css.scss:
+        * [1] [TODO] note in scss
+
+      db/some_seeds.rb:
+        * [1] [FIXME] note in db directory
+
+    OUTPUT
+  end
+
+  private
+    def run_notes_command(args = [])
+      rails "notes", args
+    end
+end