synvert-core 0.63.1 → 0.64.0

data/lib/synvert/core/rewriter/instance.rb

@@ -4,12 +4,12 @@ module Synvert::Core
   # Instance is an execution unit, it finds specified ast nodes,
   # checks if the nodes match some conditions, then add, replace or remove code.
   #
-  # One instance can contains one or many [Synvert::Core::Rewriter::Scope] and [Synvert::Rewriter::Condition].
+  # One instance can contain one or many {Synvert::Core::Rewriter::Scope} and {Synvert::Rewriter::Condition}.
   class Rewriter::Instance
     include Rewriter::Helper
 
     class << self
-      # Cached file source.
+      # Get file source.
       #
       # @param file_path [String] file path
       # @return [String] file source
@@ -23,7 +23,7 @@ module Synvert::Core
           end
       end
 
-      # Cached file ast.
+      # Get file ast.
       #
       # @param file_path [String] file path
       # @return [String] ast node for file
@@ -51,7 +51,7 @@ module Synvert::Core
         @file_ast[file_path] = nil
       end
 
-      # Reset cached file source and ast.
+      # Reset file source and ast.
       def reset
         @file_source = {}
         @file_ast = {}
@@ -69,12 +69,11 @@ module Synvert::Core
       self.class.file_source(current_file)
     end
 
-    # Initialize an instance.
+    # Initialize an Instance.
     #
     # @param rewriter [Synvert::Core::Rewriter]
     # @param file_patterns [Array<String>] pattern list to find files, e.g. ['spec/**/*_spec.rb']
-    # @param block [Block] block code to find nodes, match conditions and rewrite code.
-    # @return [Synvert::Core::Rewriter::Instance]
+    # @yield block code to find nodes, match conditions and rewrite code.
     def initialize(rewriter, file_patterns, &block)
       @rewriter = rewriter
       @actions = []
@@ -84,44 +83,14 @@ module Synvert::Core
     end
 
     # Process the instance.
-    # It finds all files, for each file, it executes the block code, gets all rewrite actions,
-    # and rewrite source code back to original file.
+    # It finds specified files, for each file, it executes the block code, rewrites the original code,
+    # then write the code back to the original file.
     def process
       @file_patterns.each do |file_pattern|
         Dir.glob(File.join(Configuration.path, file_pattern)).each do |file_path|
-          next if Configuration.skip_files.include? file_path
+          next if Configuration.skip_files.include?(file_path)
 
-          begin
-            puts file_path if Configuration.show_run_process
-            conflict_actions = []
-            source = +self.class.file_source(file_path)
-            ast = self.class.file_ast(file_path)
-
-            @current_file = file_path
-
-            process_with_node ast do
-              begin
-                instance_eval(&@block)
-              rescue NoMethodError
-                puts @current_node.debug_info
-                raise
-              end
-            end
-
-            if @actions.length > 0
-              @actions.sort_by! { |action| [action.begin_pos, action.end_pos] }
-              conflict_actions = get_conflict_actions
-              @actions.reverse_each do |action|
-                source[action.begin_pos...action.end_pos] = action.rewritten_code
-              end
-              @actions = []
-
-              update_file(file_path, source)
-            end
-          rescue Parser::SyntaxError
-            puts "[Warn] file #{file_path} was not parsed correctly."
-            # do nothing, iterate next file
-          end while !conflict_actions.empty?
+          process_file(file_path)
         end
       end
     end
@@ -158,159 +127,291 @@ module Synvert::Core
     # DSL #
     #######
 
-    # Parse within_node dsl, it creates a [Synvert::Core::Rewriter::WithinScope] to find recursive matching ast nodes,
+    # Parse +within_node+ dsl, it creates a {Synvert::Core::Rewriter::WithinScope} to recursively find matching ast nodes,
     # then continue operating on each matching ast node.
-    #
+    # @example
+    #   # matches User.find_by_login('test')
+    #   with_node type: 'send', message: /^find_by_/ do
+    #   end
     # @param rules [Hash] rules to find mathing ast nodes.
-    # @param options [Hash] optional, set if stop_when_match or not.
-    # @param block [Block] block code to continue operating on the matching nodes.
-    def within_node(rules, options = nil, &block)
-      options ||= { stop_when_match: false }
+    # @param options [Hash] optional
+    # @option stop_when_match [Boolean] set if stop when match, default is false
+    # @option direct [Boolean] set if find direct matching ast nodes, default is false
+    # @yield run on the matching nodes.
+    def within_node(rules, options = {}, &block)
+      options[:stop_when_match] ||= false
+      options[:direct] ||= false
       Rewriter::WithinScope.new(self, rules, options, &block).process
     end
 
     alias with_node within_node
 
-    # Parse within_direct_node dsl, it creates a [Synvert::Core::Rewriter::WithinScope] to find direct matching ast nodes,
-    # then continue operating on each matching ast node.
-    #
-    # @param rules [Hash] rules to find mathing ast nodes.
-    # @param block [Block] block code to continue operating on the matching nodes.
-    def within_direct_node(rules, &block)
-      Rewriter::WithinScope.new(self, rules, { direct: true }, &block).process
-    end
-
-    alias with_direct_node within_direct_node
-
-    # Parse goto_node dsl, it creates a [Synvert::Core::Rewriter::GotoScope] to go to a child node,
+    # Parse +goto_node+ dsl, it creates a {Synvert::Core::Rewriter::GotoScope} to go to a child node,
     # then continue operating on the child node.
-    #
+    # @example
+    #   # head status: 406
+    #   with_node type: 'send', receiver: nil, message: 'head', arguments: { size: 1, first: { type: 'hash' } } do
+    #     goto_node 'arguments.first' do
+    #     end
+    #   end
     # @param child_node_name [Symbol|String] the name of the child nodes.
     # @param block [Block] block code to continue operating on the matching nodes.
     def goto_node(child_node_name, &block)
       Rewriter::GotoScope.new(self, child_node_name, &block).process
     end
 
-    # Parse if_exist_node dsl, it creates a [Synvert::Core::Rewriter::IfExistCondition] to check
+    # Parse +if_exist_node+ dsl, it creates a {Synvert::Core::Rewriter::IfExistCondition} to check
     # if matching nodes exist in the child nodes, if so, then continue operating on each matching ast node.
-    #
+    # @example
+    #   # Klass.any_instance.stub(:message)
+    #   with_node type: 'send', message: 'stub', arguments: { first: { type: { not: 'hash' } } } do
+    #     if_exist_node type: 'send', message: 'any_instance' do
+    #     end
+    #   end
     # @param rules [Hash] rules to check mathing ast nodes.
     # @param block [Block] block code to continue operating on the matching nodes.
     def if_exist_node(rules, &block)
       Rewriter::IfExistCondition.new(self, rules, &block).process
     end
 
-    # Parse unless_exist_node dsl, it creates a [Synvert::Core::Rewriter::UnlessExistCondition] to check
+    # Parse +unless_exist_node+ dsl, it creates a {Synvert::Core::Rewriter::UnlessExistCondition} to check
     # if matching nodes doesn't exist in the child nodes, if so, then continue operating on each matching ast node.
-    #
+    # @example
+    #   # obj.stub(:message)
+    #   with_node type: 'send', message: 'stub', arguments: { first: { type: { not: 'hash' } } } do
+    #     unless_exist_node type: 'send', message: 'any_instance' do
+    #     end
+    #   end
     # @param rules [Hash] rules to check mathing ast nodes.
     # @param block [Block] block code to continue operating on the matching nodes.
     def unless_exist_node(rules, &block)
       Rewriter::UnlessExistCondition.new(self, rules, &block).process
     end
 
-    # Parse if_only_exist_node dsl, it creates a [Synvert::Core::Rewriter::IfOnlyExistCondition] to check
+    # Parse +if_only_exist_node+ dsl, it creates a {Synvert::Core::Rewriter::IfOnlyExistCondition} to check
     # if current node has only one child node and the child node matches rules,
     # if so, then continue operating on each matching ast node.
-    #
+    # @example
+    #   # it { should matcher }
+    #   with_node type: 'block', caller: { message: 'it' } do
+    #     if_only_exist_node type: 'send', receiver: nil, message: 'should' do
+    #     end
+    #   end
     # @param rules [Hash] rules to check mathing ast nodes.
     # @param block [Block] block code to continue operating on the matching nodes.
     def if_only_exist_node(rules, &block)
       Rewriter::IfOnlyExistCondition.new(self, rules, &block).process
     end
 
-    # Parse append dsl, it creates a [Synvert::Core::Rewriter::AppendAction] to
+    # Parse +append+ dsl, it creates a {Synvert::Core::Rewriter::AppendAction} to
     # append the code to the bottom of current node body.
-    #
+    # @example
+    #   # def teardown
+    #   #   clean_something
+    #   # end
+    #   # =>
+    #   # def teardown
+    #   #   clean_something
+    #   #   super
+    #   # end
+    #   with_node type: 'def', name: 'steardown' do
+    #     append 'super'
+    #   end
     # @param code [String] code need to be appended.
     def append(code)
       @actions << Rewriter::AppendAction.new(self, code).process
     end
 
-    # Parse prepend dsl, it creates a [Synvert::Core::Rewriter::PrependAction] to
+    # Parse +prepend+ dsl, it creates a {Synvert::Core::Rewriter::PrependAction} to
     # prepend the code to the top of current node body.
-    #
+    # @example
+    #   # def setup
+    #   #   do_something
+    #   # end
+    #   # =>
+    #   # def setup
+    #   #   super
+    #   #   do_something
+    #   # end
+    #   with_node type: 'def', name: 'setup' do
+    #     prepend 'super'
+    #   end
     # @param code [String] code need to be prepended.
     def prepend(code)
       @actions << Rewriter::PrependAction.new(self, code).process
     end
 
-    # Parse insert dsl, it creates a [Synvert::Core::Rewriter::InsertAction] to
-    # insert the code to the top of current node body.
-    #
+    # Parse +insert+ dsl, it creates a {Synvert::Core::Rewriter::InsertAction} to insert code.
+    # @example
+    #   # open('http://test.com')
+    #   # =>
+    #   # URI.open('http://test.com')
+    #   with_node type: 'send', receiver: nil, message: 'open' do
+    #     insert 'URI.', at: 'beginning'
+    #   end
     # @param code [String] code need to be inserted.
-    # @param at [String] insert position, beginning or end, end is the default.
+    # @param at [String] insert position, beginning or end
     # @param to [String] where to insert, if it is nil, will insert to current node.
     def insert(code, at: 'end', to: nil)
       @actions << Rewriter::InsertAction.new(self, code, at: at, to: to).process
     end
 
-    # Parse insert_after dsl, it creates a [Synvert::Core::Rewriter::InsertAfterAction] to
+    # Parse +insert_after+ dsl, it creates a {Synvert::Core::Rewriter::InsertAfterAction} to
     # insert the code next to the current node.
-    #
+    # @example
+    #   # Synvert::Application.config.secret_token = "0447aa931d42918bfb934750bb78257088fb671186b5d1b6f9fddf126fc8a14d34f1d045cefab3900751c3da121a8dd929aec9bafe975f1cabb48232b4002e4e"
+    #   # =>
+    #   # Synvert::Application.config.secret_token = "0447aa931d42918bfb934750bb78257088fb671186b5d1b6f9fddf126fc8a14d34f1d045cefab3900751c3da121a8dd929aec9bafe975f1cabb48232b4002e4e"
+    #   # Synvert::Application.config.secret_key_base = "bf4f3f46924ecd9adcb6515681c78144545bba454420973a274d7021ff946b8ef043a95ca1a15a9d1b75f9fbdf85d1a3afaf22f4e3c2f3f78e24a0a188b581df"
+    #   with_node type: 'send', message: 'secret_token=' do
+    #     insert_after "{{receiver}}.secret_key_base = \"#{SecureRandom.hex(64)}\""
+    #   end
     # @param code [String] code need to be inserted.
-    def insert_after(node)
-      @actions << Rewriter::InsertAfterAction.new(self, node).process
+    def insert_after(code)
+      @actions << Rewriter::InsertAfterAction.new(self, code).process
     end
 
-    # Parse replace_with dsl, it creates a [Synvert::Core::Rewriter::ReplaceWithAction] to
-    # replace current node with code.
-    #
+    # Parse +replace_with+ dsl, it creates a {Synvert::Core::Rewriter::ReplaceWithAction} to
+    # replace the whole code of current node.
+    # @example
+    #   # obj.stub(:foo => 1, :bar => 2)
+    #   # =>
+    #   # allow(obj).to receive_messages(:foo => 1, :bar => 2)
+    #   with_node type: 'send', message: 'stub', arguments: { first: { type: 'hash' } } do
+    #     replace_with 'allow({{receiver}}).to receive_messages({{arguments}})'
+    #   end
     # @param code [String] code need to be replaced with.
     def replace_with(code)
       @actions << Rewriter::ReplaceWithAction.new(self, code).process
     end
 
-    # Parse replace with dsl, it creates a [Synvert::Core::Rewriter::ReplaceAction] to
-    # replace child nodes with code.
-    #
+    # Parse +replace+ dsl, it creates a {Synvert::Core::Rewriter::ReplaceAction} to
+    # replace the code of specified child nodes.
+    # @example
+    #   # assert(object.empty?)
+    #   # =>
+    #   # assert_empty(object)
+    #   with_node type: 'send', receiver: nil, message: 'assert', arguments: { size: 1, first: { type: 'send', message: 'empty?', arguments: { size: 0 } } } do
+    #     replace :message, with: 'assert_empty'
+    #     replace :arguments, with: '{{arguments.first.receiver}}'
+    #   end
     # @param selectors [Array<Symbol>] selector names of child node.
     # @param with [String] code need to be replaced with.
     def replace(*selectors, with:)
       @actions << Rewriter::ReplaceAction.new(self, *selectors, with: with).process
     end
 
-    # Parse replace_erb_stmt_with_expr dsl, it creates a [Synvert::Core::Rewriter::ReplaceErbStmtWithExprAction] to
+    # Parse +replace_erb_stmt_with_expr+ dsl, it creates a {Synvert::Core::Rewriter::ReplaceErbStmtWithExprAction} to
     # replace erb stmt code to expr code.
+    # @example
+    #   # <% form_for post do |f| %>
+    #   # <% end %>
+    #   # =>
+    #   # <%= form_for post do |f| %>
+    #   # <% end %>
+    #   with_node type: 'block', caller: { type: 'send', receiver: nil, message: 'form_for' } do
+    #     replace_erb_stmt_with_expr
+    #   end
     def replace_erb_stmt_with_expr
       @actions << Rewriter::ReplaceErbStmtWithExprAction.new(self).process
     end
 
-    # Parse remove dsl, it creates a [Synvert::Core::Rewriter::RemoveAction] to remove current node.
+    # Parse +remove+ dsl, it creates a {Synvert::Core::Rewriter::RemoveAction} to remove current node.
+    # @example
+    #   with_node type: 'send', message: { in: %w[puts p] } do
+    #     remove
+    #   end
     def remove
       @actions << Rewriter::RemoveAction.new(self).process
     end
 
-    # Parse delete dsl, it creates a [Synvert::Core::Rewriter::DeleteAction] to delete child nodes.
-    #
+    # Parse +delete+ dsl, it creates a {Synvert::Core::Rewriter::DeleteAction} to delete child nodes.
+    # @example
+    #   # FactoryBot.create(...)
+    #   # =>
+    #   # create(...)
+    #   with_node type: 'send', receiver: 'FactoryBot', message: 'create' do
+    #     delete :receiver, :dot
+    #   end
     # @param selectors [Array<Symbol>] selector names of child node.
     def delete(*selectors)
       @actions << Rewriter::DeleteAction.new(self, *selectors).process
     end
 
-    # Parse wrap with dsl, it creates a [Synvert::Core::Rewriter::WrapAction] to
+    # Parse +wrap+ dsl, it creates a {Synvert::Core::Rewriter::WrapAction} to
     # wrap current node with code.
-    #
+    # @example
+    #   # class Foobar
+    #   # end
+    #   # =>
+    #   # module Synvert
+    #   #   class Foobar
+    #   #   end
+    #   # end
+    #   within_node type: 'class' do
+    #     wrap with: 'module Synvert'
+    #   end
     # @param with [String] code need to be wrapped with.
-    # @param indent [Integer] number of whitespaces.
+    # @param indent [Integer, nil] number of whitespaces.
     def wrap(with:, indent: nil)
       @actions << Rewriter::WrapAction.new(self, with: with, indent: indent).process
     end
 
-    # Parse warn dsl, it creates a [Synvert::Core::Rewriter::Warning] to save warning message.
-    #
+    # Parse +warn+ dsl, it creates a {Synvert::Core::Rewriter::Warning} to save warning message.
+    # @example
+    #   within_files 'vendor/plugins' do
+    #     warn 'Rails::Plugin is deprecated and will be removed in Rails 4.0. Instead of adding plugins to vendor/plugins use gems or bundler with path or git dependencies.'
+    #   end
     # @param message [String] warning message.
     def warn(message)
       @rewriter.add_warning Rewriter::Warning.new(self, message)
     end
 
-    # Any value but nil.
+    # Match any value but nil.
+    # @example
+    #   type: 'hash', nothing_value: 'true', status_value: any_value
+    # @return [Synvert::Core::Rewriter::AnyValue]
     def any_value
       Rewriter::AnyValue.new
     end
 
     private
 
+    # Process one file.
+    #
+    # @param file_path [String]
+    def process_file(file_path)
+      begin
+        puts file_path if Configuration.show_run_process
+        conflict_actions = []
+        source = +self.class.file_source(file_path)
+        ast = self.class.file_ast(file_path)
+
+        @current_file = file_path
+
+        process_with_node(ast) do
+          instance_eval(&@block)
+        rescue NoMethodError
+          puts @current_node.debug_info
+          raise
+        end
+
+        if @actions.length > 0
+          @actions.sort_by! { |action| [action.begin_pos, action.end_pos] }
+          conflict_actions = get_conflict_actions
+          @actions.reverse_each do |action|
+            source[action.begin_pos...action.end_pos] = action.rewritten_code
+          end
+          @actions = []
+
+          update_file(file_path, source)
+        end
+      rescue Parser::SyntaxError
+        puts "[Warn] file #{file_path} was not parsed correctly."
+        # do nothing, iterate next file
+      end while !conflict_actions.empty?
+    end
+
     # It changes source code from bottom to top, and it can change source code twice at the same time,
     # So if there is an overlap between two actions, it removes the conflict actions and operate them in the next loop.
     def get_conflict_actions

data/lib/synvert/core/rewriter/ruby_version.rb

@@ -17,13 +17,13 @@ module Synvert::Core
     # @return [Boolean] true if matches, otherwise false.
     def match?
       if File.exist?(File.join(Configuration.path, '.ruby-version'))
-        versionFile = '.ruby-version'
+        version_file = '.ruby-version'
       elsif File.exist?(File.join(Configuration.path, '.rvmrc'))
-        versionFile = '.rvmrc'
+        version_file = '.rvmrc'
       end
-      return true unless versionFile
+      return true unless version_file
 
-      version = File.read(File.join(Configuration.path, versionFile))
+      version = File.read(File.join(Configuration.path, version_file))
       Gem::Version.new(version) >= Gem::Version.new(@version)
     end
   end

data/lib/synvert/core/rewriter/scope/goto_scope.rb

@@ -3,18 +3,17 @@
 module Synvert::Core
   # Go to and change its scope to a child node.
   class Rewriter::GotoScope < Rewriter::Scope
-    # Initialize a scope
+    # Initialize a GotoScope.
     #
     # @param instance [Synvert::Core::Rewriter::Instance]
-    # @param child_node_name [Symbol|string]
-    # @param block [Block]
+    # @param child_node_name [Symbol|String] name of child node
+    # @yield run on the child node
     def initialize(instance, child_node_name, &block)
-      @instance = instance
+      super(instance, &block)
       @child_node_name = child_node_name
-      @block = block
     end
 
-    # Go to a child now, then run the block code with the the child node.
+    # Go to a child now, then run the block code on the the child node.
     def process
       current_node = @instance.current_node
       return unless current_node

data/lib/synvert/core/rewriter/scope/within_scope.rb

@@ -3,17 +3,16 @@
 module Synvert::Core
   # WithinScope finds out nodes which match rules, then changes its scope to matching node.
   class Rewriter::WithinScope < Rewriter::Scope
-    # Initialize a scope
+    # Initialize a WithinScope.
     #
     # @param instance [Synvert::Core::Rewriter::Instance]
     # @param rules [Hash]
     # @param options [Hash]
-    # @param block [Block]
+    # @yield run on all matching nodes
     def initialize(instance, rules, options = {}, &block)
-      @instance = instance
+      super(instance, &block)
       @rules = rules
       @options = options
-      @block = block
     end
 
     # Find out the matching nodes.
@@ -43,6 +42,8 @@ module Synvert::Core
     private
 
     # Find the matching nodes only in current or direct children.
+    #
+    # @param current_node [Parser::AST::Node]
     def find_direct_matching_nodes(current_node)
       matching_nodes = []
       if current_node.is_a?(Parser::AST::Node)
@@ -62,6 +63,8 @@ module Synvert::Core
     end
 
     # Find matching nodes in all recursive children.
+    #
+    # @param current_node [Parser::AST::Node]
     def find_recursive_matching_nodes(current_node)
       matching_nodes = []
       if current_node.is_a?(Parser::AST::Node)
@@ -81,6 +84,8 @@ module Synvert::Core
     end
 
     # Find matching nodes in recursive children but do not continue on matching nodes.
+    #
+    # @param current_node [Parser::AST::Node]
     def find_matching_nodes(current_node)
       matching_nodes = []
       if current_node.is_a?(Parser::AST::Node)

data/lib/synvert/core/rewriter/scope.rb

@@ -3,5 +3,13 @@
 module Synvert::Core
   # Scope finds out nodes which match rules.
   class Rewriter::Scope
+    # Initialize a Scope
+    #
+    # @param instance [Synvert::Core::Rewriter::Instance]
+    # @yield run on a scope
+    def initialize(instance, &block)
+      @instance = instance
+      @block = block
+    end
   end
 end

data/lib/synvert/core/rewriter/warning.rb

@@ -3,7 +3,7 @@
 module Synvert::Core
   # Warning is used to save warning message.
   class Rewriter::Warning
-    # Initialize a warning.
+    # Initialize a Warning.
     #
     # @param instance [Synvert::Core::Rewriter::Instance]
     # @param message [String] warning message.