transpec 0.2.6 → 1.0.0

data/README.md.erb

@@ -2,7 +2,7 @@
 
 # Transpec
 
-**Transpec** automatically converts your specs into latest [RSpec](http://rspec.info/) syntax with static analysis.
+**Transpec** automatically converts your specs into latest [RSpec](http://rspec.info/) syntax with static and dynamic code analysis.
 
 This aims to facilitate smooth transition to RSpec 3.
 
@@ -61,12 +61,12 @@ END
 Transpec would convert it to the following form:
 
 ```ruby
-<%= Transpec::Rewriter.new.rewrite(example) -%>
+<%= Transpec::Converter.new.convert(example) -%>
 ```
 
-### Real Examples
+### Actual Examples
 
-You can see real conversion examples below:
+You can see actual conversion examples below:
 
 * https://github.com/yujinakayama/guard/commit/transpec-demo
 * https://github.com/yujinakayama/mail/commit/transpec-demo
@@ -86,27 +86,32 @@ Before converting your specs:
 * Run `rspec` and check if all the specs pass.
 * Ensure the Git repository is clean. (You don't want to mix up your changes and Transpec's changes, right?)
 
-Then, run `transpec` (using `--commit-message` is recommended) in the project root directory:
+Then, run `transpec` (using `--generate-commit-message` is recommended) in the project root directory:
 
 ```bash
 $ cd some-project
-$ transpec --commit-message
-Processing spec/spec_helper.rb
-Processing spec/spec_spec.rb
-Processing spec/support/file_helper.rb
-Processing spec/support/shared_context.rb
-Processing spec/transpec/ast/scanner_spec.rb
-Processing spec/transpec/ast/scope_stack_spec.rb
+$ transpec --generate-commit-message
+Copying project for dynamic analysis...
+Running dynamic analysis with command "bundle exec rspec"...
+...............................................................................
+...................
+
+Finished in 13.07 seconds
+100 examples, 0 failures
+
+Converting spec/spec_helper.rb
+Converting spec/support/cache_helper.rb
+Converting spec/support/file_helper.rb
+Converting spec/support/shared_context.rb
+Converting spec/transpec/ast/node_spec.rb
 ```
 
-This will convert and overwrite all spec files in the `spec` directory.
+This will run your specs, convert them, and overwrite all spec files in the `spec` directory.
 
 After the conversion, run `rspec` again and check whether all pass:
 
 ```bash
 $ bundle exec rspec
-# ...
-843 examples, 0 failures
 ```
 
 If all pass, commit the changes with auto-generated message:
@@ -135,7 +140,23 @@ Processing spec/spec_spec.rb
 Processing spec/support/file_helper.rb
 ```
 
-### `-m/--commit-message`
+### `-s/--skip-dynamic-analysis`
+
+Skip dynamic analysis and convert with only static analysis. Note that specifying this option decreases the conversion accuracy.
+
+### `-c/--rspec-command`
+
+Specify command to run RSpec that is used for dynamic analysis.
+
+Transpec needs to run your specs in copied project directory for dynamic analysis.
+If your project requires some special setup or commands to run specs, use this option.
+`bundle exec rspec` is used by default.
+
+```bash
+$ transpec --rspec-command "./some_special_setup.sh && bundle exec rspec"
+```
+
+### `-m/--generate-commit-message`
 
 Generate commit message that describes conversion summary.
 Currently only Git is supported.
@@ -146,24 +167,25 @@ When you commit, you need to run the following command to use the generated mess
 $ git commit -eF .git/COMMIT_EDITMSG
 ```
 
-### `-d/--disable`
+### `-k/--keep`
 
-Disable specific conversions.
+Keep specific syntaxes by disabling conversions.
 
 ```bash
-$ transpec --disable expect_to_receive,allow_to_receive
+$ transpec --keep should_receive,stub
 ```
 
-#### Available conversion types
+#### Available syntax types
 
-Conversion Type     | Target Syntax                    | Converted Syntax
---------------------|----------------------------------|----------------------------
+Type             | Target Syntax                    | Converted Syntax
+-----------------|----------------------------------|----------------------------
 <%=
 conversion_type_table = <<END
-`expect_to_matcher` | `obj.should matcher`             | `expect(obj).to matcher`
-`expect_to_receive` | `obj.should_receive`             | `expect(obj).to receive`
-`allow_to_receive`  | `obj.stub`                       | `allow(obj).to receive`
-`deprecated`        | `obj.stub!`, `mock('foo')`, etc. | `obj.stub`, `double('foo')`
+`should`         | `obj.should matcher`             | `expect(obj).to matcher`
+`should_receive` | `obj.should_receive`             | `expect(obj).to receive`
+`stub`           | `obj.stub`                       | `allow(obj).to receive`
+`have_items`     | `expect(obj).to have(x).items`   | `expect(obj.size).to eq(x)`
+`deprecated`     | `obj.stub!`, `mock('foo')`, etc. | `obj.stub`, `double('foo')`
 END
 
 types_in_readme = conversion_type_table.lines.map do |line|
@@ -171,11 +193,11 @@ types_in_readme = conversion_type_table.lines.map do |line|
   first_column.gsub(/[^\w]/, '').to_sym
 end.sort
 
-types_in_code = Transpec::CLI::CONFIG_ATTRS_FOR_CLI_TYPES.keys.sort
+types_in_code = Transpec::OptionParser.available_conversion_types.sort
 
 unless types_in_readme == types_in_code
   types_missing_description = types_in_code - types_in_readme
-  fail "No descriptions for conversion types #{types_missing_description}"
+  fail "No descriptions for syntax types #{types_missing_description}"
 end
 
 conversion_type_table
@@ -215,7 +237,7 @@ END
 -%>
 
 <%=
-Transpec::Rewriter.new.rewrite(parenthesizing_example).gsub(
+Transpec::Converter.new.convert(parenthesizing_example).gsub(
   'original spec',
   'converted spec'
 )
@@ -224,8 +246,8 @@ Transpec::Rewriter.new.rewrite(parenthesizing_example).gsub(
 <%=
 configuration = Transpec::Configuration.new
 configuration.parenthesize_matcher_arg = false
-rewriter = Transpec::Rewriter.new(configuration)
-rewriter.rewrite(parenthesizing_example)
+converter = Transpec::Converter.new(configuration)
+converter.convert(parenthesizing_example)
   .gsub(
     'original spec',
     'converted spec with -p/--no-parentheses-matcher-arg option'
@@ -238,7 +260,7 @@ rewriter.rewrite(parenthesizing_example)
 -%>
 ```
 
-## Troubleshooting
+## Inconvertible Specs
 
 You might see the following warning while conversion:
 
@@ -266,11 +288,11 @@ end
 
 ### Reason
 
-* `should` is defined on `Kernel` (included by `Object`), so you can use `should` almost everywhere.
-* `expect` is defined on `RSpec::Matchers` (included by `RSpec::Core::ExampleGroup`), so you can use `expect` only where `self` is an instance of `RSpec::Core::ExampleGroup`.
+* `should` is defined on `Kernel` module that is included by `Object` class, so you can use `should` almost everywhere.
+* `expect` is defined on `RSpec::Matchers` module that is included by `RSpec::Core::ExampleGroup` class, so you can use `expect` only where `self` is an instance of `RSpec::Core::ExampleGroup` (i.e. in `it` blocks, `:each` hook blocks or included methods).
 
 With the above example, in the context of `1.should == 1`, the `self` is an instance of `MyAwesomeTestRunner`.
-So Transpec tracks contexts and skips conversion if the target syntax cannot be converted in a case like this.
+Transpec tracks contexts and skips conversion if the target syntax cannot be converted in a case like this.
 
 ### Solution
 
@@ -291,8 +313,8 @@ expect(obj).not_to matcher
 expect(obj).to_not matcher # with `--negative-form to_not`
 ```
 
-* Disabled by: `--disable expect_to_matcher`
-* Related Information: [Myron Marston » RSpec's New Expectation Syntax](http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax)
+* Disabled by: `--keep should`
+* See also: [Myron Marston » RSpec's New Expectation Syntax](http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax)
 
 ### Operator matchers
 
@@ -312,7 +334,7 @@ expect('string').to match(/^str/)
 expect([1, 2, 3]).to match_array([2, 1, 3])
 ```
 
-* Related Information: [Myron Marston » RSpec's New Expectation Syntax](http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax#almost_all_matchers_are_supported)
+* See also: [(Almost) All Matchers Are Supported - RSpec's New Expectation Syntax](http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax#almost_all_matchers_are_supported)
 
 ### `be_close` matcher
 
@@ -324,10 +346,43 @@ expect([1, 2, 3]).to match_array([2, 1, 3])
 (1.0 / 3.0).should be_within(0.001).of(0.333)
 ```
 
-* Disabled by: `--disable deprecated`
-* Related Information: [New be within matcher and RSpec.deprecate fix · rspec/rspec-expectations](https://github.com/rspec/rspec-expectations/pull/32)
+* Disabled by: `--keep deprecated`
+* See also: [New be within matcher and RSpec.deprecate fix · rspec/rspec-expectations](https://github.com/rspec/rspec-expectations/pull/32)
+
+### `have(n).items` matcher
+
+```ruby
+# Targets
+expect(collection).to have(3).items
+expect(collection).to have_exactly(3).items
+expect(collection).to have_at_least(3).items
+expect(collection).to have_at_most(3).items
+collection.should have(3).items
+
+expect(team).to have(3).players
+
+# Assume #players is a private method.
+expect(team).to have(3).players
+
+# Converted
+expect(collection.size).to eq(3)
+expect(collection.size).to be >= 3
+expect(collection.size).to be <= 3
+collection.size.should == 3  # with `--keep should`
+
+expect(team.players.size).to eq(3)
+
+# have(n).items matcher invokes #players even if it's a private method.
+expect(team.send(:players).size).to eq(3)
+```
+
+You have the option to continue using `have(n).items` matcher with [rspec-collection_matchers](https://github.com/rspec/rspec-collection_matchers) that is an external gem extracted from `rspec-expectations`.
+If you choose so, disable this conversion with `--keep have_items`.
+
+* Disabled by: `--keep have_items`
+* See also: [Expectations: have(x).items matchers will be moved into an external gem - The Plan for RSpec 3](http://myronmars.to/n/dev-blog/2013/07/the-plan-for-rspec-3#expectations__matchers_will_be_moved_into_an_external_gem)
 
-### Expectations on Proc
+### Expectations on Block
 
 ```ruby
 # Targets
@@ -339,8 +394,8 @@ proc { do_something }.should raise_error
 expect { do_something }.to raise_error
 ```
 
-* Disabled by: `--disable expect_to_matcher`
-* Related Information: [Myron Marston » RSpec's New Expectation Syntax](http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax#unification_of_block_vs_value_syntaxes)
+* Disabled by: `--keep should`
+* See also: [Unification of Block vs. Value Syntaxes - RSpec's New Expectation Syntax](http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax#unification_of_block_vs_value_syntaxes)
 
 ### Negative error expectations with specific error
 
@@ -353,11 +408,11 @@ lambda { do_something }.should_not raise_error(SomeErrorClass)
 
 # Converted
 expect { do_something }.not_to raise_error
-lambda { do_something }.should_not raise_error # with `--disable expect_to_matcher`
+lambda { do_something }.should_not raise_error # with `--keep should`
 ```
 
-* Disabled by: `--disable deprecated`
-* Related Information: [Consider deprecating `expect { }.not_to raise_error(SpecificErrorClass)` · rspec/rspec-expectations](https://github.com/rspec/rspec-expectations/issues/231)
+* Disabled by: `--keep deprecated`
+* See also: [Consider deprecating `expect { }.not_to raise_error(SpecificErrorClass)` · rspec/rspec-expectations](https://github.com/rspec/rspec-expectations/issues/231)
 
 ### Message expectations
 
@@ -371,8 +426,8 @@ expect(obj).to receive(:foo)
 expect_any_instance_of(SomeClass).to receive(:foo)
 ```
 
-* Disabled by: `--disable expect_to_receive`
-* Related Information: [RSpec's new message expectation syntax - Tea is awesome.](http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/)
+* Disabled by: `--keep should_receive`
+* See also: [RSpec's new message expectation syntax - Tea is awesome.](http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/)
 
 ### Message expectations that are actually method stubs
 
@@ -386,14 +441,14 @@ SomeClass.any_instance.should_receive(:foo).at_least(0)
 
 # Converted
 allow(obj).to receive(:foo)
-obj.stub(:foo) # with `--disable allow_to_receive`
+obj.stub(:foo) # with `--keep stub`
 
 allow_any_instance_of(SomeClass).to receive(:foo)
-SomeClass.any_instance.stub(:foo) # with `--disable allow_to_receive`
+SomeClass.any_instance.stub(:foo) # with `--keep stub`
 ```
 
-* Disabled by: `--disable deprecated`
-* Related Information: [Don't allow at_least(0) · rspec/rspec-mocks](https://github.com/rspec/rspec-mocks/issues/133)
+* Disabled by: `--keep deprecated`
+* See also: [Don't allow at_least(0) · rspec/rspec-mocks](https://github.com/rspec/rspec-mocks/issues/133)
 
 ### Method stubs
 
@@ -418,8 +473,8 @@ allow(obj).to receive(:bar).and_return(2)
 allow_any_instance_of(SomeClass).to receive(:foo)
 ```
 
-* Disabled by: `--disable allow_to_receive`
-* Related Information: [RSpec's new message expectation syntax - Tea is awesome.](http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/)
+* Disabled by: `--keep stub`
+* See also: [RSpec's new message expectation syntax - Tea is awesome.](http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/)
 
 ### Deprecated method stub aliases
 
@@ -429,12 +484,12 @@ obj.stub!(:foo)
 obj.unstub!(:foo)
 
 # Converted
-obj.stub(:foo) # with `--disable allow_to_receive`
+obj.stub(:foo) # with `--keep stub`
 obj.unstub(:foo)
 ```
 
-* Disabled by: `--disable deprecated`
-* Related Information: [Consider deprecating and/or removing #stub! and #unstub! at some point · rspec/rspec-mocks](https://github.com/rspec/rspec-mocks/issues/122)
+* Disabled by: `--keep deprecated`
+* See also: [Consider deprecating and/or removing #stub! and #unstub! at some point · rspec/rspec-mocks](https://github.com/rspec/rspec-mocks/issues/122)
 
 ### Method stubs with deprecated specification of number of times
 
@@ -445,11 +500,11 @@ obj.stub(:foo).at_least(0)
 
 # Converted
 allow(obj).to receive(:foo)
-obj.stub(:foo) # with `--disable allow_to_receive`
+obj.stub(:foo) # with `--keep stub`
 ```
 
-* Disabled by: `--disable deprecated`
-* Related Information: [Don't allow at_least(0) · rspec/rspec-mocks](https://github.com/rspec/rspec-mocks/issues/133)
+* Disabled by: `--keep deprecated`
+* See also: [Don't allow at_least(0) · rspec/rspec-mocks](https://github.com/rspec/rspec-mocks/issues/133)
 
 ### Deprecated test double aliases
 
@@ -462,8 +517,8 @@ mock('something')
 double('something')
 ```
 
-* Disabled by: `--disable deprecated`
-* Related Information: [Deprecate "stub" for doubles · rspec/rspec-mocks](https://github.com/rspec/rspec-mocks/issues/214)
+* Disabled by: `--keep deprecated`
+* See also: [Deprecate "stub" for doubles · rspec/rspec-mocks](https://github.com/rspec/rspec-mocks/issues/214)
 
 ## Compatibility
 

data/lib/transpec/ast/node.rb

@@ -5,6 +5,41 @@ require 'parser'
 module Transpec
   module AST
     class Node < Parser::AST::Node
+      def initialize(type, children = [], properties = {})
+        @properties = {}
+
+        super
+
+        each_child_node do |child_node|
+          child_node.parent_node = self
+        end
+      end
+
+      def parent_node
+        @properties[:parent_node]
+      end
+
+      def parent_node=(node)
+        @properties[:parent_node] = node
+      end
+
+      protected :parent_node=
+
+      def each_ancestor_node(&block)
+        return to_enum(__method__) unless block_given?
+
+        if parent_node
+          yield parent_node
+          parent_node.each_ancestor_node(&block)
+        end
+
+        self
+      end
+
+      def ancestor_nodes
+        each_ancestor_node.to_a
+      end
+
       def each_child_node
         return to_enum(__method__) unless block_given?
 
@@ -32,6 +67,12 @@ module Transpec
       def descendent_nodes
         each_descendent_node.to_a
       end
+
+      private
+
+      def properties
+        @properties ||= {}
+      end
     end
   end
 end

data/lib/transpec/base_rewriter.rb

@@ -0,0 +1,55 @@
+# coding: utf-8
+
+require 'transpec/ast/builder'
+require 'parser/current'
+
+module Transpec
+  class BaseRewriter
+    def rewrite_file!(file_path)
+      source = File.read(file_path)
+      rewritten_source = rewrite(source, file_path)
+      return if source == rewritten_source
+      File.write(file_path, rewritten_source)
+    end
+
+    def rewrite(source, name = '(string)')
+      source_buffer = create_source_buffer(source, name)
+      ast = parse(source_buffer)
+
+      source_rewriter = Parser::Source::Rewriter.new(source_buffer)
+      failed_overlapping_rewrite = false
+      source_rewriter.diagnostics.consumer = proc do
+        failed_overlapping_rewrite = true
+        fail OverlappedRewriteError
+      end
+
+      process(ast, source_rewriter)
+
+      rewritten_source = source_rewriter.process
+      rewritten_source = rewrite(rewritten_source, name) if failed_overlapping_rewrite
+
+      rewritten_source
+    end
+
+    private
+
+    def process(ast, source_rewriter)
+      fail NotImplementedError
+    end
+
+    def create_source_buffer(source, name)
+      source_buffer = Parser::Source::Buffer.new(name)
+      source_buffer.source = source
+      source_buffer
+    end
+
+    def parse(source_buffer)
+      builder = AST::Builder.new
+      parser = Parser::CurrentRuby.new(builder)
+      ast = parser.parse(source_buffer)
+      ast
+    end
+
+    class OverlappedRewriteError < StandardError; end
+  end
+end