node_mutation 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f708082625b70a33be17a520d51fab328979f7640f6125f7cec8a4f8c0fa348c
+  data.tar.gz: 71219747c6be37cb7282658c5dc6087f33ac63ed195de48ab29f2aa79347ea85
+SHA512:
+  metadata.gz: 74f6fdb99bec0cd69ae0310ebc728661981ab7e7c41624e2409238426095cfec7576f1905d49f7e9d25393723b9c43dbe6ebf9c72730df38a19308e68682fc49
+  data.tar.gz: d2323af8c25e3a69779848be92594075970eb3c22b6c26fc411bc95710f51c9d37881a32c4196b3330eb28544d05dcbf72ef45521bce2e61025ea1ab5681eaae

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# NodeMutation
+
+## 1.0.0 (2022-07-01)
+
+* Initial release

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in node_mutation.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "parser"
+gem "parser_node_ext"
+gem "guard"
+gem "guard-rspec"
+gem "fakefs", require: 'fakefs/safe'
+gem "pp"

data/Gemfile.lock

@@ -0,0 +1,96 @@
+PATH
+  remote: .
+  specs:
+    node_mutation (1.0.0)
+      activesupport
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (7.0.3)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    ast (2.4.2)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.10)
+    diff-lcs (1.5.0)
+    fakefs (1.8.0)
+    ffi (1.15.5)
+    formatador (1.1.0)
+    guard (2.18.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.13.0)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    i18n (1.10.0)
+      concurrent-ruby (~> 1.0)
+    listen (3.7.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    lumberjack (1.2.8)
+    method_source (1.0.0)
+    minitest (5.16.1)
+    nenv (0.3.0)
+    notiffany (0.1.3)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    parser (3.1.2.0)
+      ast (~> 2.4.1)
+    parser_node_ext (0.2.0)
+      parser
+    pp (0.3.0)
+      prettyprint
+    prettyprint (0.1.1)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    rake (13.0.6)
+    rb-fsevent (0.11.1)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-support (3.11.0)
+    shellany (0.0.1)
+    thor (1.2.1)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+
+PLATFORMS
+  x86_64-darwin-21
+  x86_64-linux
+
+DEPENDENCIES
+  fakefs
+  guard
+  guard-rspec
+  node_mutation!
+  parser
+  parser_node_ext
+  pp
+  rake (~> 13.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   2.3.7

data/Guardfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb') { "spec" }
+end

data/README.md

@@ -0,0 +1,78 @@
+# NodeMutation
+
+NodeMutation provides a set of APIs to rewrite node source code.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'node_mutation'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install node_mutation
+
+## Usage
+
+1. initialize the NodeMutation instance:
+
+```ruby
+require 'node_mutation'
+
+mutation = NodeMutation.new(file_path, source)
+```
+
+2. call the rewrite apis:
+
+```ruby
+# append the code to the current node.
+mutation.append node, 'include FactoryGirl::Syntax::Methods'
+# delete source code of the child ast node
+mutation.delete node, :dot, :message, and_comma: true
+# insert code to the ast node.
+mutation.insert node, 'URI.', at: 'beginning'
+# insert code next to the ast node.
+mutation.insert_after node, '{{arguments.first}}.include FactoryGirl::Syntax::Methods'
+# prepend code to the ast node.
+mutation.prepend node, '{{arguments.first}}.include FactoryGirl::Syntax::Methods'
+# remove source code of the ast node
+mutation.remove(node: Node)
+# replace child node of the ast node with new code
+mutation.replace node, :message, with: 'test'
+# replace the ast node with new code
+mutation.replace_with node, 'create {{arguments}}'
+# wrap node within a block, class or module
+mutation.wrap node, with: 'module Foo'
+```
+
+3. process actions and write the new source code to file:
+
+```ruby
+mutation.process
+```
+
+## Write Adapter
+
+Different parsers, like parse and ripper, will generate different AST nodes, to make NodeMutation work for them all,
+we define an [Adapter](https://github.com/xinminlabs/node-mutation-ruby/blob/main/lib/node_mutation/adapter.rb) interface,
+if you implement the Adapter interface, you can set it as NodeMutation's adapter.
+
+```typescript
+NodeMutation.configure({ adapter: ParserAdapter.new })
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/xinminlabs/node_mutation.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/code.rb

@@ -0,0 +1,4 @@
+class Foobar
+  def foo; end
+  def bar; end
+end

data/lib/node_mutation/action/append_action.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# AppendAction appends code to the bottom of node body.
+class NodeMutation::AppendAction < NodeMutation::Action
+  private
+
+  END_LENGTH = "\nend".length
+
+  # Calculate the begin the end positions.
+  def calculate_position
+    @start = NodeMutation.adapter.get_end(@node) - NodeMutation.adapter.get_start_loc(@node).column - END_LENGTH
+    @end = @start
+  end
+
+  # Indent of the node.
+  #
+  # @param node [Parser::AST::Node]
+  # @return [String] n times whitesphace
+  def indent(node)
+    ' ' *  (NodeMutation.adapter.get_start_loc(node).column + DEFAULT_INDENT)
+  end
+end

data/lib/node_mutation/action/delete_action.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# DeleteAction deletes child nodes.
+class NodeMutation::DeleteAction < NodeMutation::Action
+  # Initialize a DeleteAction.
+  #
+  # @param node [Node]
+  # @param selectors [Array<Symbol, String>] used to select child nodes
+  # @option and_comma [Boolean] delete extra comma.
+  def initialize(node, *selectors, and_comma: false)
+    super(node, nil)
+    @selectors = selectors
+    @and_comma = and_comma
+  end
+
+  # The rewritten code, always empty string.
+  def new_code
+    ''
+  end
+
+  private
+
+  # Calculate the begin and end positions.
+  def calculate_position
+    @start = @selectors.map { |selector| NodeMutation.adapter.child_node_range(@node, selector) }
+                            .compact.map(&:start).min
+    @end = @selectors.map { |selector| NodeMutation.adapter.child_node_range(@node, selector) }
+                          .compact.map(&:end).max
+    squeeze_spaces
+    remove_comma if @and_comma
+  end
+end

data/lib/node_mutation/action/insert_action.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# InsertAction to add code to the node.
+class NodeMutation::InsertAction < NodeMutation::Action
+  # Initialize an InsertAction.
+  #
+  # @param ndoe [Node]
+  # @param code [String] to be inserted
+  # @param at [String] position to insert, beginning or end
+  # @param to [<nil|String>] name of child node
+  def initialize(node, code, at: 'end', to: nil)
+    super(node, code)
+    @at = at
+    @to = to
+  end
+
+  # The rewritten source code.
+  #
+  # @return [String] rewritten code.
+  def new_code
+    rewritten_source
+  end
+
+  private
+
+  # Calculate the begin and end positions.
+  def calculate_position
+    @start =
+      if @at == 'end'
+        if @to
+          NodeMutation.adapter.child_node_range(@node, @to).end
+        else
+          NodeMutation.adapter.get_end(@node)
+        end
+      else
+        if @to
+          NodeMutation.adapter.child_node_range(@node, @to).start
+        else
+          NodeMutation.adapter.get_start(@node)
+        end
+      end
+    @end = @start
+  end
+end

data/lib/node_mutation/action/insert_after_action.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# InsertAfterAction to insert code next to the node.
+class NodeMutation::InsertAfterAction < NodeMutation::Action
+  private
+
+  # Calculate the begin and end positions.
+  def calculate_position
+    @start = NodeMutation.adapter.get_end(@node)
+    @end = @start
+  end
+
+  # Indent of the node.
+  #
+  # @param node [Parser::AST::Node]
+  # @return [Integer] indent size
+  def indent(node)
+    ' ' * NodeMutation.adapter.get_start_loc(node).column
+  end
+end

data/lib/node_mutation/action/prepend_action.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# PrependAction to prepend code to the top of node body.
+class NodeMutation::PrependAction < NodeMutation::Action
+  private
+
+  DO_LENGTH = ' do'.length
+
+  # Calculate the begin and end positions.
+  def calculate_position
+    node_start = NodeMutation.adapter.get_start(@node)
+    node_source = NodeMutation.adapter.get_source(@node)
+    first_line = node_source.split("\n").first
+    @start = first_line.end_with?("do") ? node_start + first_line.index("do") + "do".length : node_start + first_line.length
+    @end = @start
+  end
+
+  # Indent of the node.
+  #
+  # @param node [Parser::AST::Node]
+  # @return [String] n times whitesphace
+  def indent(node)
+    ' ' * (NodeMutation.adapter.get_start_loc(node).column + DEFAULT_INDENT)
+  end
+end

data/lib/node_mutation/action/remove_action.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# RemoveAction to remove current node.
+class NodeMutation::RemoveAction < NodeMutation::Action
+  # Initialize a RemoveAction.
+  #
+  # @param node [Node]
+  # @param options [Hash] options.
+  # @option and_comma [Boolean] delete extra comma.
+  def initialize(node, and_comma: false)
+    super(node, nil)
+    @and_comma = and_comma
+  end
+
+  # The rewritten code, always empty string.
+  def new_code
+    ''
+  end
+
+  private
+
+  # Calculate the begin the end positions.
+  def calculate_position
+    if take_whole_line?
+      @start = start_index
+      @end = end_index
+      squeeze_lines
+    else
+      @start = NodeMutation.adapter.get_start(@node)
+      @end = NodeMutation.adapter.get_end(@node)
+      squeeze_spaces
+      remove_comma if @and_command
+    end
+  end
+
+  # Check if the source code of current node takes the whole line.
+  #
+  # @return [Boolean]
+  def take_whole_line?
+    NodeMutation.adapter.get_source(@node) == file_source[start_index...end_index].strip
+  end
+
+  # Get the start position of the line
+  def start_index
+    index = file_source[0..NodeMutation.adapter.get_start(@node)].rindex("\n")
+    index ? index + "\n".length : NodeMutation.adapter.get_start(@node)
+  end
+
+  # Get the end position of the line
+  def end_index
+    index = file_source[NodeMutation.adapter.get_end(@node)..-1].index("\n")
+    index ? NodeMutation.adapter.get_end(@node) + index + "\n".length : NodeMutation.adapter.get_end(@node)
+  end
+end

data/lib/node_mutation/action/replace_action.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# ReplaceAction to replace child node with code.
+class NodeMutation::ReplaceAction < NodeMutation::Action
+  # Initailize a ReplaceAction.
+  #
+  # @param node [Node]
+  # @param selectors [Array<Symbol|String>] used to select child nodes
+  # @param with [String] the new code
+  def initialize(node, *selectors, with:)
+    super(node, with)
+    @selectors = selectors
+  end
+
+  # The rewritten source code.
+  #
+  # @return [String] rewritten code.
+  def new_code
+    rewritten_source
+  end
+
+  private
+
+  # Calculate the begin the end positions.
+  def calculate_position
+    @start = @selectors.map { |selector| NodeMutation.adapter.child_node_range(@node, selector).start }.min
+    @end = @selectors.map { |selector| NodeMutation.adapter.child_node_range(@node, selector).end }.max
+  end
+end

data/lib/node_mutation/action/replace_with_action.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# ReplaceWithAction to replace code.
+class NodeMutation::ReplaceWithAction < NodeMutation::Action
+  # The rewritten source code with proper indent.
+  #
+  # @return [String] rewritten code.
+  def new_code
+    if rewritten_source.include?("\n")
+      new_code = []
+      rewritten_source.split("\n").each_with_index do |line, index|
+        new_code << (index == 0 ? line : indent + line)
+      end
+      new_code.join("\n")
+    else
+      rewritten_source
+    end
+  end
+
+  private
+
+  # Calculate the begin the end positions.
+  def calculate_position
+    @start = NodeMutation.adapter.get_start(@node)
+    @end = NodeMutation.adapter.get_end(@node)
+  end
+
+  # Indent of the node
+  #
+  # @return [String] n times whitesphace
+  def indent
+    ' ' * NodeMutation.adapter.get_start_loc(@node).column
+  end
+end

data/lib/node_mutation/action/wrap_action.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# WrapAction to wrap node within a block, class or module.
+#
+# Note: if WrapAction is conflicted with another action (begin_pos and end_pos are overlapped),
+# we have to put those 2 actions into 2 within_file scopes.
+class NodeMutation::WrapAction < NodeMutation::Action
+  # Initialize a WrapAction.
+  #
+  # @param node [Node]
+  # @param with [String] new code to wrap
+  def initialize(node, with:)
+    super(node, with)
+    @indent = NodeMutation.adapter.get_start_loc(@node).column
+  end
+
+  # The rewritten source code.
+  #
+  # @return [String] rewritten code.
+  def new_code
+    "#{@code}\n#{' ' * @indent}" +
+      NodeMutation.adapter.get_source(@node).split("\n").map { |line| "  #{line}" }
+            .join("\n") +
+      "\n#{' ' * @indent}end"
+  end
+
+  private
+
+  # Calculate the begin the end positions.
+  def calculate_position
+    @start = NodeMutation.adapter.get_start(@node)
+    @end = NodeMutation.adapter.get_end(@node)
+  end
+end

data/lib/node_mutation/action.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# Action defines rewriter action, insert, replace or delete code.
+class NodeMutation::Action
+  DEFAULT_INDENT = 2
+
+  # @!attribute [r] start
+  #   @return [Integer] start position
+  # @!attribute [r] end
+  #   @return [Integer] end position
+  attr_reader :start, :end
+
+  # Initialize an action.
+  #
+  # @param node [Node]
+  # @param code [String] new code to insert, replace or delete.
+  def initialize(node, code)
+    @node = node
+    @code = code
+  end
+
+  # Calculate begin and end positions, and return self.
+  #
+  # @return [NodeMutation::Action] self
+  def process
+    calculate_position
+    self
+  end
+
+  # The rewritten source code with proper indent.
+  #
+  # @return [String] rewritten code.
+  def new_code
+    if rewritten_source.split("\n").length > 1
+      "\n\n" + rewritten_source.split("\n").map { |line| indent(@node) + line }.join("\n")
+    else
+      "\n" + indent(@node) + rewritten_source
+    end
+  end
+
+  protected
+
+  # Calculate the begin the end positions.
+  #
+  # @abstract
+  def calculate_position
+    raise NotImplementedError, 'must be implemented by subclasses'
+  end
+
+  # The rewritten source code.
+  #
+  # @return [String] rewritten source code.
+  def rewritten_source
+    @rewritten_source ||= NodeMutation.adapter.rewritten_source(@node, @code)
+  end
+
+  # Squeeze spaces from source code.
+  def squeeze_spaces
+    if file_source[@start - 1] == ' ' && file_source[@end] == ' '
+      @start -= 1
+    end
+  end
+
+  # Squeeze empty lines from source code.
+  def squeeze_lines
+    lines = file_source.split("\n")
+    begin_line = NodeMutation.adapter.get_start_loc(@node).line
+    end_line = NodeMutation.adapter.get_end_loc(@node).line
+    before_line_is_blank = begin_line == 1 || lines[begin_line - 2] == ''
+    after_line_is_blank = lines[end_line] == ''
+
+    if lines.length > 1 && before_line_is_blank && after_line_is_blank
+      @end_pos += "\n".length
+    end
+  end
+
+  # Remove unused comma.
+  # e.g. `foobar(foo, bar)`, if we remove `foo`, the comma should also be removed,
+  # the code should be changed to `foobar(bar)`.
+  def remove_comma
+    if ',' == file_source[@start - 1]
+      @start -= 1
+    elsif ', ' == file_source[@start - 2, 2]
+      @start -= 2
+    elsif ', ' == file_source[@end, 2]
+      @end += 2
+    elsif ',' == file_source[@end]
+      @end += 1
+    end
+  end
+
+  # Return file source.
+  #
+  # @return [String]
+  def file_source
+    @file_source ||= NodeMutation.adapter.file_content(@node)
+  end
+end

data/lib/node_mutation/adapter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+class NodeMutation::Adapter
+  # Get source code of the ast node
+  # @param node [Node] ast node
+  # @return [String] source code
+  def get_source(node)
+    raise NotImplementedError, "get_source is not implemented"
+  end
+
+  # Replace the child node selector with child node source code
+  # @param node [Node] ast node
+  # @param code [String] code with child node selector, e.g. `Boolean({{expression.operand.operand}})`
+  # @return [String] code with source code of child node selector,
+  # @example # source code of ast node is `!!foobar`, code is `Boolean({{expression.operand.operand}})`,
+  # it will return `Boolean(foobar)`
+  def rewritten_source(node, code)
+    raise NotImplementedError, "rewritten_source is not implemented"
+  end
+
+  # The file content of the ast node file
+  # @param node [Node] ast node
+  # @return file content
+  def file_content(node)
+    raise NotImplementedError, "file_content is not implemented"
+  end
+
+  # Get the start/end range of the child node
+  # @param node [Node] ast node
+  # @param child_name [String] child name selector
+  # @return [{ start: Number, end: Number }] child node range
+  def child_node_range(node, child_name)
+    raise NotImplementedError, "child_node_range is not implemented"
+  end
+
+  # Get start position of ast node
+  # @param node [Node] ast node
+  # @return [Number] start position
+  def get_start(node)
+    raise NotImplementedError, "get_start is not implemented"
+  end
+
+  # Get end position of ast node
+  # @param node [Node] ast node
+  # @return [Number] end position
+  def get_end(node)
+    raise NotImplementedError, "get_end is not implemented"
+  end
+
+  # Get start location of ast node
+  # @param node [Node] ast node
+  # @return [{ line: Number, column: Number }] start location
+  def get_start_loc(node)
+    raise NotImplementedError, "get_start_loc is not implemented"
+  end
+
+  # Get end location of ast node
+  # @param node [Node] ast node
+  # @return [{ line: Number, column: Number }] end location
+  def get_end_loc(node)
+    raise NotImplementedError, "get_end_loc is not implemented"
+  end
+
+  # Get indent of ast node
+  # @param node [Node] ast node
+  # @return [Number] indent
+  def get_indent(node)
+    raise NotImplementedError, "get_indent is not implemented"
+  end
+end

data/lib/node_mutation/parser_adapter.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+class NodeMutation::ParserAdapter < NodeMutation::Adapter
+  def get_source(node)
+    node.loc.expression.source
+  end
+
+  def rewritten_source(node, code)
+    code.gsub(/{{(.*?)}}/m) do
+      old_code = Regexp.last_match(1)
+      if node.respond_to?(old_code.split('.').first)
+        evaluated = child_node_by_name(node, old_code)
+        case evaluated
+        when Parser::AST::Node
+          if evaluated.type == :args
+            evaluated.loc.expression.source[1...-1]
+          else
+            evaluated.loc.expression.source
+          end
+        when Array
+          if evaluated.size > 0
+            file_source = file_content(evaluated.first)
+            source = file_source[evaluated.first.loc.expression.begin_pos...evaluated.last.loc.expression.end_pos]
+            lines = source.split "\n"
+            lines_count = lines.length
+            if lines_count > 1 && lines_count == evaluated.size
+              new_code = []
+              lines.each_with_index { |line, index|
+                new_code << (index == 0 ? line : line[evaluated.first.indent - 2..-1])
+              }
+              new_code.join("\n")
+            else
+              source
+            end
+          end
+        when String, Symbol, Integer, Float
+          evaluated
+        when NilClass
+          'nil'
+        else
+          raise Synvert::Core::MethodNotSupported, "rewritten_source is not handled for #{evaluated.inspect}"
+        end
+      else
+        "{{#{old_code}}}"
+      end
+    end
+  end
+
+  def file_content(node)
+    node.loc.expression.source_buffer.source
+  end
+
+  def child_node_range(node, child_name)
+    if node.is_a?(Array)
+      direct_child_name, nested_child_name = child_name.split('.', 2)
+      child_node = direct_child_name =~ /\A\d+\z/ ? node[direct_child_name.to_i - 1] : node.send(direct_child_name)
+      if nested_child_name
+        return child_node_range(child_node, nested_child_name)
+      elsif child_node
+        return OpenStruct.new(
+          start: child_node.loc.expression.begin_pos,
+          end: child_node.loc.expression.end_pos
+        )
+      else
+        raise MethodNotSupported, "child_node_range is not handled for #{get_source(node)}, child_name: #{child_name}"
+      end
+    end
+
+    case [node.type, child_name.to_sym]
+    when %i[block pipes], %i[def parentheses], %i[defs parentheses]
+      OpenStruct.new(
+        start: node.arguments.first.loc.expression.begin_pos - 1,
+        end: node.arguments.last.loc.expression.end_pos + 1
+      )
+    when %i[block arguments], %i[def arguments], %i[defs arguments]
+      OpenStruct.new(
+        start: node.arguments.first.loc.expression.begin_pos,
+        end: node.arguments.last.loc.expression.end_pos
+      )
+    when %i[class name], %i[def name], %i[defs name]
+      OpenStruct.new(start: node.loc.name.begin_pos, end: node.loc.name.end_pos)
+    when %i[defs dot]
+      OpenStruct.new(start: node.loc.operator.begin_pos, end: node.loc.operator.end_pos) if node.loc.operator
+    when %i[defs self]
+      OpenStruct.new(start: node.loc.operator.begin_pos - 'self'.length, end: node.loc.operator.begin_pos)
+    when %i[send dot], %i[csend dot]
+      OpenStruct.new(start: node.loc.dot.begin_pos, end: node.loc.dot.end_pos) if node.loc.dot
+    when %i[send message], %i[csend message]
+      if node.loc.operator
+        OpenStruct.new(start: node.loc.selector.begin_pos, end: node.loc.operator.end_pos)
+      else
+        OpenStruct.new(start: node.loc.selector.begin_pos, end: node.loc.selector.end_pos)
+      end
+    when %i[send parentheses], %i[csend parentheses]
+      if node.loc.begin && node.loc.end
+        OpenStruct.new(start: node.loc.begin.begin_pos, end: node.loc.end.end_pos)
+      end
+    else
+      direct_child_name, nested_child_name = child_name.to_s.split('.', 2)
+      if node.respond_to?(direct_child_name)
+        child_node = node.send(direct_child_name)
+
+        return child_node_range(child_node, nested_child_name) if nested_child_name
+
+        return nil if child_node.nil?
+
+        if child_node.is_a?(Parser::AST::Node)
+          return(
+            OpenStruct.new(
+              start: child_node.loc.expression.begin_pos,
+              end: child_node.loc.expression.end_pos
+            )
+          )
+        end
+
+        # arguments
+        return nil if child_node.empty?
+
+        return(
+          OpenStruct.new(
+            start: child_node.first.loc.expression.begin_pos,
+            end: child_node.last.loc.expression.end_pos
+          )
+        )
+      end
+    end
+  end
+
+  def get_start(node)
+    node.loc.expression.begin_pos
+  end
+
+  def get_end(node)
+    node.loc.expression.end_pos
+  end
+
+  def get_start_loc(node)
+    begin_loc = node.loc.expression.begin
+    OpenStruct.new(line: begin_loc.line, column: begin_loc.column)
+  end
+
+  def get_end_loc(node)
+    end_loc = node.loc.expression.end
+    OpenStruct.new(line: end_loc.line, column: end_loc.column)
+  end
+
+  def get_indent(node)
+    file_content(node).split("\n")[get_start_loc(node).line - 1][/\A */].size
+  end
+
+  private
+
+  def child_node_by_name(node, child_name)
+    direct_child_name, nested_child_name = child_name.to_s.split('.', 2)
+
+    if node.is_a?(Array)
+      child_direct_child_node = direct_child_name =~ /\A\d+\z/ ? node[direct_child_name.to_i - 1] : node.send(direct_child_name)
+      return child_node_by_name(child_direct_child_node, nested_child_name) if nested_child_name
+      return child_direct_child_node if child_direct_child_node
+    end
+
+    if node.respond_to?(direct_child_name)
+      child_node = node.send(direct_child_name)
+
+      return child_node_by_name(child_node, nested_child_name) if nested_child_name
+
+      return nil if child_node.nil?
+
+      return child_node if child_node.is_a?(Parser::AST::Node)
+
+      return child_node
+    end
+  end
+end

data/lib/node_mutation/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class NodeMutation
+  VERSION = "1.0.0"
+end

data/lib/node_mutation.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require 'ostruct'
+require 'active_support/core_ext/array'
+
+require_relative "node_mutation/version"
+
+class NodeMutation
+  class MethodNotSupported < StandardError; end
+  class ConflictActionError < StandardError; end
+
+  KEEPING_RUNNING = 1
+  THROW_ERROR = 2
+
+  autoload :Adapter, "node_mutation/adapter"
+  autoload :ParserAdapter, "node_mutation/parser_adapter"
+  autoload :Action, 'node_mutation/action'
+  autoload :AppendAction, 'node_mutation/action/append_action'
+  autoload :DeleteAction, 'node_mutation/action/delete_action'
+  autoload :InsertAction, 'node_mutation/action/insert_action'
+  autoload :InsertAfterAction, 'node_mutation/action/insert_after_action'
+  autoload :RemoveAction, 'node_mutation/action/remove_action'
+  autoload :PrependAction, 'node_mutation/action/prepend_action'
+  autoload :ReplaceAction, 'node_mutation/action/replace_action'
+  autoload :ReplaceErbStmtWithExprAction, 'node_mutation/action/replace_erb_stmt_with_expr_action'
+  autoload :ReplaceWithAction, 'node_mutation/action/replace_with_action'
+  autoload :WrapAction, 'node_mutation/action/wrap_action'
+
+  attr_reader :actions
+
+  # Configure NodeMutation
+  # @param [Hash] options options to configure
+  # @option options [NodeMutation::Adapter] :adapter the adpater
+  def self.configure(options)
+    if options[:adapter]
+      @adapter = options[:adapter]
+    end
+    if options[:strategy]
+      @strategy = options[:strategy]
+    end
+  end
+
+  # Get the adapter
+  # @return [NodeMutation::Adapter] current adapter, by default is {NodeMutation::ParserAdapter}
+  def self.adapter
+    @adapter ||= ParserAdapter.new
+  end
+
+  # Get the strategy
+  # @return [Integer] current strategy, could be {NodeMutation::KEEPING_RUNNING} or {NodeMutation::THROW_ERROR},
+  # by default is {NodeMutation::KEEPING_RUNNING}
+  def self.strategy
+    @strategy ||= KEEP_RUNNING
+  end
+
+  # Initialize a NodeMutation.
+  # @param file_path [String] file path
+  # @param source [String] source of the file
+  def initialize(file_path, source)
+    @file_path = file_path
+    @source = +source
+    @actions = []
+  end
+
+  # Append code to the ast node.
+  # @param node [Node] ast node
+  # @param code [String] new code to append
+  # @example
+  # source code of the ast node is
+  #     def teardown
+  #       clean_something
+  #     end
+  # then we call
+  #     mutation.append(node, 'super')
+  # the source code will be rewritten to
+  #     def teardown
+  #       clean_something
+  #       super
+  #     end
+  def append(node, code)
+    @actions << AppendAction.new(node, code).process
+  end
+
+  # Delete source code of the child ast node.
+  # @param node [Node] ast node
+  # @param selectors [Array<Symbol>] selector names of child node.
+  # @param options [Hash]
+  # @option and_comma [Boolean] delete extra comma.
+  # @example
+  # source code of the ast node is
+  #     FactoryBot.create(...)
+  # then we call
+  #     mutation.delete(node, :receiver, :dot)
+  # the source code will be rewritten to
+  #     create(...)
+  def delete(node, *selectors, **options)
+    @actions << DeleteAction.new(node, *selectors, **options).process
+  end
+
+  # Insert code to the ast node.
+  # @param node [Node] ast node
+  # @param code [String] code need to be inserted.
+  # @param at [String] insert position, beginning or end
+  # @param to [String] where to insert, if it is nil, will insert to current node.
+  # @example
+  # source code of the ast node is
+  #     open('http://test.com')
+  # then we call
+  #     mutation.insert(node, 'URI.', at: 'beginning')
+  # the source code will be rewritten to
+  #     URI.open('http://test.com')
+  def insert(node, code, at: 'end', to: nil)
+    @actions << InsertAction.new(node, code, at: at, to: to).process
+  end
+
+  # Insert code next to the ast node.
+  # @param node [Node] ast node
+  # @param code [String] new code to insert.
+  # @example
+  # source code of the ast node is
+  #     Synvert::Application.config.secret_token = "0447aa931d42918bfb934750bb78257088fb671186b5d1b6f9fddf126fc8a14d34f1d045cefab3900751c3da121a8dd929aec9bafe975f1cabb48232b4002e4e"
+  # then we call
+  #     mutation.insert_after(node, "{{receiver}}.secret_key_base = \"#{SecureRandom.hex(64)}\"")
+  # the source code will be rewritten to
+  #     Synvert::Application.config.secret_token = "0447aa931d42918bfb934750bb78257088fb671186b5d1b6f9fddf126fc8a14d34f1d045cefab3900751c3da121a8dd929aec9bafe975f1cabb48232b4002e4e"
+  #     Synvert::Application.config.secret_key_base = "bf4f3f46924ecd9adcb6515681c78144545bba454420973a274d7021ff946b8ef043a95ca1a15a9d1b75f9fbdf85d1a3afaf22f4e3c2f3f78e24a0a188b581df"
+  def insert_after(node, code)
+    @actions << InsertAfterAction.new(node, code).process
+  end
+
+  # Prepend code to the ast node.
+  # @param node [Node] ast node
+  # @param code [String] new code to prepend.
+  # @example
+  # source code of the ast node is
+  #     def setup
+  #       do_something
+  #     end
+  # then we call
+  #     mutation.prepend(node, 'super')
+  # the source code will be rewritten to
+  #     def setup
+  #       super
+  #       do_something
+  #     end
+  def prepend(node, code)
+    @actions << PrependAction.new(node, code).process
+  end
+
+  # Remove source code of the ast node.
+  # @param node [Node] ast node
+  # @param options [Hash] options.
+  # @option and_comma [Boolean] delete extra comma.
+  # @example
+  # source code of the ast node is
+  #     puts "test"
+  # then we call
+  #     mutation.remove(node)
+  # the source code will be removed
+  def remove(node, **options)
+    @actions << RemoveAction.new(node, **options).process
+  end
+
+  # Replace child node of the ast node with new code.
+  # @param node [Node] ast node
+  # @param selectors [Array<Symbol>] selector names of child node.
+  # @param with [String] code need to be replaced with.
+  # @example
+  # source code of the ast node is
+  #     assert(object.empty?)
+  # then we call
+  #     replace :message, with: 'assert_empty'
+  #     replace :arguments, with: '{{arguments.first.receiver}}'
+  # the source code will be rewritten to
+  #     assert_empty(object)
+  def replace(node, *selectors, with:)
+    @actions << ReplaceAction.new(node, *selectors, with: with).process
+  end
+
+  # Replace source code of the ast node with new code.
+  # @param node [Node] ast node
+  # @param code [String] code need to be replaced with.
+  # @example
+  # source code of the ast node is
+  #     obj.stub(:foo => 1, :bar => 2)
+  # then we call
+  #     replace_with 'allow({{receiver}}).to receive_messages({{arguments}})'
+  # the source code will be rewritten to
+  #     allow(obj).to receive_messages(:foo => 1, :bar => 2)
+  def replace_with(node, code)
+    @actions << ReplaceWithAction.new(node, code).process
+  end
+
+  # Wrap source code of the ast node with new code.
+  # @param node [Node] ast node
+  # @param with [String] code need to be wrapped with.
+  # @example
+  # source code of the ast node is
+  #     class Foobar
+  #     end
+  # then we call
+  #     wrap(node, with: 'module Synvert')
+  # the source code will be rewritten to
+  #     module Synvert
+  #       class Foobar
+  #       end
+  #     end
+  def wrap(node, with:)
+    @actions << WrapAction.new(node, with: with).process
+  end
+
+  # Read the source code from file path,
+  # rewrite the source code based on all actions,
+  # then write the new source code back to the file.
+  #
+  # If there's an action range conflict,
+  # it will raise a ConflictActionError if strategy is set to THROW_ERROR,
+  # it will process all non conflicted actions and return `{ conflict: true }`
+  # if strategy is set to KEEP_RUNNING.
+  # @return {{conflict: Boolean}} if actions are conflicted
+  def process
+    conflict_actions = []
+    if @actions.length > 0
+      @actions.sort_by! { |action| [action.start, action.end] }
+      conflict_actions = get_conflict_actions
+      if conflict_actions.size > 0 && NodeMutation.strategy == THROW_ERROR
+        raise ConflictActionError, "mutation actions are conflicted"
+      end
+      @actions.reverse_each do |action|
+        @source[action.start...action.end] = action.new_code
+      end
+      @actions = []
+
+      File.write(@file_path, @source)
+    end
+    OpenStruct.new(conflict: !conflict_actions.empty?)
+  end
+
+  private
+
+  # 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
+    i = @actions.length - 1
+    j = i - 1
+    conflict_actions = []
+    return [] if i < 0
+
+    start = @actions[i].start
+    while j > -1
+      if start < @actions[j].end
+        conflict_actions << @actions.delete_at(j)
+      else
+        i = j
+        start = @actions[i].start
+      end
+      j -= 1
+    end
+    conflict_actions
+  end
+end

data/node_mutation.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/node_mutation/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "node_mutation"
+  spec.version = NodeMutation::VERSION
+  spec.authors = ["Richard Huang"]
+  spec.email = ["flyerhzm@gmail.com"]
+
+  spec.summary = "ast node mutation apis"
+  spec.description = "ast node mutation apis"
+  spec.homepage = "https://github.com/xinminlabs/node-mutation-ruby"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/xinminlabs/node-mutation-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/xinminlabs/node-mutation-ruby/blob/master/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency "activesupport"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/sig/node_mutation/adapter.rbs

@@ -0,0 +1,19 @@
+class NodeMutation::Adapter[T]
+  def get_source: (node: T) -> String
+
+  def rewritten_source: (node: T, code: String) -> String
+
+  def file_content: (node: T) -> String
+
+  def child_node_range: (node: T, child_name: String) -> OpenStruct
+
+  def get_start: (node: T) -> Integer
+
+  def get_end: (node: T) -> Integer
+
+  def get_start_loc: (node: T) -> OpenStruct
+
+  def get_end_loc: (node: T) -> OpenStruct
+
+  def get_indent: (node: T) -> Integer
+end

data/sig/node_mutation.rbs

@@ -0,0 +1,43 @@
+module NodeMutation[T]
+  VERSION: Stringo
+
+  class MethodNotSupported < StandardError
+  end
+
+  class ConflictActionError < StandardError
+  end
+
+  KEEPING_RUNNING: Integer
+
+  THROW_ERROR: Integer
+
+  attr_reader actions: Array[NodeMutation::Action]
+
+  def self.configure: (options: { adapter: NodeMutation::Adapter, strategry: Integer }) -> void
+
+  def self.adapter: () -> NodeMutation::Adapter
+
+  def self.strategry: () -> Integer
+
+  def initialize: (file_path: String, source: String) -> NodeMutation
+
+  def append: (node: T, code: String) -> void
+
+  def delete: (node: T, *selectors: Array[String], **options: { and_comma: bool }) -> void
+
+  def insert: (node: T, code: String, ?at: "beginning" | "end", ?to: nil | String) -> void
+
+  def insert_after: (node: T, code: String) -> void
+
+  def prepend: (node: T, code: String) -> void
+
+  def remove: (node: T, **options: { and_comma: bool }) -> void
+
+  def replace: (node: T, *selectors: Array[String], with: String) -> void
+
+  def replace_with: (node: T, code: String) -> void
+
+  def wrap: (node: T, with: String) -> void
+
+  def process: () -> void
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: node_mutation
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Richard Huang
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-07-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ast node mutation apis
+email:
+- flyerhzm@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- Guardfile
+- README.md
+- Rakefile
+- code.rb
+- lib/node_mutation.rb
+- lib/node_mutation/action.rb
+- lib/node_mutation/action/append_action.rb
+- lib/node_mutation/action/delete_action.rb
+- lib/node_mutation/action/insert_action.rb
+- lib/node_mutation/action/insert_after_action.rb
+- lib/node_mutation/action/prepend_action.rb
+- lib/node_mutation/action/remove_action.rb
+- lib/node_mutation/action/replace_action.rb
+- lib/node_mutation/action/replace_with_action.rb
+- lib/node_mutation/action/wrap_action.rb
+- lib/node_mutation/adapter.rb
+- lib/node_mutation/parser_adapter.rb
+- lib/node_mutation/version.rb
+- node_mutation.gemspec
+- sig/node_mutation.rbs
+- sig/node_mutation/adapter.rbs
+homepage: https://github.com/xinminlabs/node-mutation-ruby
+licenses: []
+metadata:
+  homepage_uri: https://github.com/xinminlabs/node-mutation-ruby
+  source_code_uri: https://github.com/xinminlabs/node-mutation-ruby
+  changelog_uri: https://github.com/xinminlabs/node-mutation-ruby/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: ast node mutation apis
+test_files: []