Document rake task

Author: kddnewton

.github/workflows/main.yml

@@ -38,7 +38,7 @@ jobs:
         ruby-version: '3.1'
     - name: Check
       run: |
-        bundle exec rake check
+        bundle exec rake stree:check
         bundle exec rubocop
 
   automerge:

CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 ## [Unreleased]
 
+### Added
+
+- [#74](https://github.com/ruby-syntax-tree/syntax_tree/pull/74) - Add Rake test to run check and format commands.
+
 ## [2.5.0] - 2022-05-13
 
 ### Added

README.md

@@ -38,6 +38,7 @@ It is built with only standard library dependencies. It additionally ships with
   - [syntaxTree/visualizing](#syntaxtreevisualizing)
 - [Plugins](#plugins)
 - [Integration](#integration)
+  - [Rake](#rake)
   - [RuboCop](#rubocop)
   - [VSCode](#vscode)
 - [Contributing](#contributing)
@@ -436,6 +437,46 @@ Below are listed all of the "official" language plugins hosted under the same Gi
 
 Syntax Tree's goal is to seemlessly integrate into your workflow. To this end, it provides a couple of additional tools beyond the CLI and the Ruby library.
 
+### Rake
+
+Syntax Tree ships with the ability to define [rake](https://github.com/ruby/rake) tasks that will trigger runs of the CLI. To define them in your application, add the following configuration to your `Rakefile`:
+
+```ruby
+require "syntax_tree/rake_tasks"
+SyntaxTree::Rake::CheckTask.new
+SyntaxTree::Rake::WriteTask.new
+```
+
+These calls will define `rake stree:check` and `rake stree:write` (equivalent to calling `stree check` and `stree write` respectively). You can configure them by either passing arguments to the `new` method or by using a block.
+
+#### `name`
+
+If you'd like to change the default name of the rake task, you can pass that as the first optioon, as in:
+
+```ruby
+SyntaxTree::Rake::WriteTask.new(:format)
+```
+
+#### `source_files`
+
+If you wanted to configure Syntax Tree to check or write different files than the default (`lib/**/*.rb`), you can set the `source_files` field, as in:
+
+```ruby
+SyntaxTree::Rake::WriteTask.new do |t|
+  t.source_files = FileList[%w[Gemfile Rakefile lib/**/*.rb test/**/*.rb]]
+end
+```
+
+#### `plugins`
+
+If you're running Syntax Tree with plugins (either your own or the pre-built ones), you can pass that to the `plugins` field, as in:
+
+```ruby
+SyntaxTree::Rake::WriteTask.new do |t|
+  t.plugins = ["plugin/single_quotes"]
+end
+```
+
 ### RuboCop
 
 RuboCop and Syntax Tree serve different purposes, but there is overlap with some of RuboCop's functionality. Syntax Tree provides a RuboCop configuration file to disable rules that are redundant with Syntax Tree. To use this configuration file, add the following snippet to the top of your project's `.rubocop.yml`:

Rakefile

@@ -2,6 +2,7 @@
 
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "syntax_tree/rake_tasks"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
@@ -11,24 +12,8 @@ end
 
 task default: :test
 
-FILEPATHS = %w[
-  Gemfile
-  Rakefile
-  syntax_tree.gemspec
-  lib/**/*.rb
-  test/*.rb
-].freeze
+SOURCE_FILES =
+  FileList[%w[Gemfile Rakefile syntax_tree.gemspec lib/**/*.rb test/*.rb]]
 
-task :syntax_tree do
-  $:.unshift File.expand_path("lib", __dir__)
-  require "syntax_tree"
-  require "syntax_tree/cli"
-end
-
-task check: :syntax_tree do
-  exit SyntaxTree::CLI.run(["check"] + FILEPATHS)
-end
-
-task format: :syntax_tree do
-  exit SyntaxTree::CLI.run(["write"] + FILEPATHS)
-end
+SyntaxTree::Rake::CheckTask.new { |t| t.source_files = SOURCE_FILES }
+SyntaxTree::Rake::WriteTask.new { |t| t.source_files = SOURCE_FILES }

lib/syntax_tree/rake/check_task.rb

@@ -3,6 +3,9 @@
 require "rake"
 require "rake/tasklib"
 
+require "syntax_tree"
+require "syntax_tree/cli"
+
 module SyntaxTree
   module Rake
     # A Rake task that runs check on a set of source files.
@@ -21,16 +24,25 @@ module Rake
     #
     class CheckTask < ::Rake::TaskLib
       # Name of the task.
-      # Defaults to :stree_check.
+      # Defaults to :"stree:check".
       attr_accessor :name
 
       # Glob pattern to match source files.
       # Defaults to 'lib/**/*.rb'.
       attr_accessor :source_files
 
-      def initialize(name = :stree_check)
+      # The set of plugins to require.
+      # Defaults to [].
+      attr_accessor :plugins
+
+      def initialize(
+        name = :"stree:check",
+        source_files = ::Rake::FileList["lib/**/*.rb"],
+        plugins = []
+      )
         @name = name
-        @source_files = "lib/**/*.rb"
+        @source_files = source_files
+        @plugins = plugins
 
         yield self if block_given?
         define_task
@@ -44,7 +56,10 @@ def define_task
       end
 
       def run_task
-        SyntaxTree::CLI.run(["check", source_files].compact)
+        arguments = ["check"]
+        arguments << "--plugins=#{plugins.join(",")}" if plugins.any?
+
+        SyntaxTree::CLI.run(arguments + Array(source_files))
       end
     end
   end

lib/syntax_tree/rake/write_task.rb

@@ -3,6 +3,9 @@
 require "rake"
 require "rake/tasklib"
 
+require "syntax_tree"
+require "syntax_tree/cli"
+
 module SyntaxTree
   module Rake
     # A Rake task that runs format on a set of source files.
@@ -21,16 +24,25 @@ module Rake
     #
     class WriteTask < ::Rake::TaskLib
       # Name of the task.
-      # Defaults to :stree_write.
+      # Defaults to :"stree:write".
       attr_accessor :name
 
       # Glob pattern to match source files.
       # Defaults to 'lib/**/*.rb'.
       attr_accessor :source_files
 
-      def initialize(name = :stree_write)
+      # The set of plugins to require.
+      # Defaults to [].
+      attr_accessor :plugins
+
+      def initialize(
+        name = :"stree:write",
+        source_files = ::Rake::FileList["lib/**/*.rb"],
+        plugins = []
+      )
         @name = name
-        @source_files = "lib/**/*.rb"
+        @source_files = source_files
+        @plugins = plugins
 
         yield self if block_given?
         define_task
@@ -44,7 +56,10 @@ def define_task
       end
 
       def run_task
-        SyntaxTree::CLI.run(["write", source_files].compact)
+        arguments = ["write"]
+        arguments << "--plugins=#{plugins.join(",")}" if plugins.any?
+
+        SyntaxTree::CLI.run(arguments + Array(source_files))
       end
     end
   end

lib/syntax_tree/rake_tasks.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "rake/check_task"
+require_relative "rake/write_task"

test/check_task_test.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require "syntax_tree/rake_tasks"
+
+module SyntaxTree
+  module Rake
+    class CheckTaskTest < Minitest::Test
+      Invoke = Struct.new(:args)
+
+      def test_check_task
+        source_files = "{app,config,lib}/**/*.rb"
+        CheckTask.new { |t| t.source_files = source_files }
+
+        invoke = nil
+        SyntaxTree::CLI.stub(:run, ->(args) { invoke = Invoke.new(args) }) do
+          ::Rake::Task["stree:check"].invoke
+        end
+
+        assert_equal(["check", source_files], invoke.args)
+      end
+
+      def test_write_task
+        source_files = "{app,config,lib}/**/*.rb"
+        WriteTask.new { |t| t.source_files = source_files }
+
+        invoke = nil
+        SyntaxTree::CLI.stub(:run, ->(args) { invoke = Invoke.new(args) }) do
+          ::Rake::Task["stree:write"].invoke
+        end
+
+        assert_equal(["write", source_files], invoke.args)
+      end
+    end
+  end
+end