ffast 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 238c006c217b8838c23488cbfafe15c3e694d69a
-  data.tar.gz: '095e4dfdba32adf0ddf52da166c27a93c8bbd3bb'
+SHA256:
+  metadata.gz: c75d9b66509133b2f2579a03d663a80ece65421f309819f6c04b67c641973816
+  data.tar.gz: d172f92548e5080074d9edc2ec23bbc0a3febd3cfcfe1296d743a0a219ebfb8f
 SHA512:
-  metadata.gz: 73ce257e59e1bd96cbc62d4b23225cd50f5bfa551ca64eeb38da4693bc832b14203d2335d6e55e389b74fd5feba1e164ed2f1adbcdbeca0a14676115e1df5c02
-  data.tar.gz: 3133c3f337da981e728ab42ed9bf61eafc907715c3c6bb7c210ff38d6a6c73d3e87cf88625d8cac4dcfa648d3f909b3e6625a502d96c9a2316e04436086c7f8f
+  metadata.gz: 12f1c29903c12fe53e0b1a6b9c8c54664eb34411dbb9ae88c813359fe0df342c4a0c4168f13598a357281992ba89f7e5a1bdf8196e4217ce6b451d60d1cef364
+  data.tar.gz: 98e8a7f6b9a374197124b2a0b293fececd46bf396f86d6981de27193b9dc5c92532bc66763a31f446dae4d638967ea601f1348f633bbee6ca383ab5a2d63e54d

data/.travis.yml

@@ -1,8 +1,8 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.3.3
-before_install: gem install bundler -v 1.13.7
+  - 2.5.0
+before_install: gem install bundler -v 1.16.1
 before_script:
   - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
   - chmod +x ./cc-test-reporter

data/README.md

@@ -7,6 +7,8 @@ Fast is a "Find AST" tool to help you search in the code abstract syntax tree.
 Ruby allow us to do the same thing in a few ways then it's hard to check
 how the code is written.
 
+Check the official documentation: https://jonatas.github.io/fast.
+
 ## Syntax for find in AST
 
 The current version cover the following elements:
@@ -27,18 +29,6 @@ The syntax is inspired on [RuboCop Node Pattern](https://github.com/bbatsov/rubo
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'ffast'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
     $ gem install ffast
 
 ## How it works
@@ -230,7 +220,7 @@ name:
 Fast.match?(ast,'(def $_ ... (send (send nil _) \1))') # => [:name]
 ```
 
-### Fast.search
+## Fast.search
 
 Search allows you to go deeply in the AST, collecting nodes that matches with
 the expression. It also returns captures if they exist.
@@ -245,14 +235,14 @@ If you use captures, it returns the node and the captures respectively:
 Fast.search(code('a = 1'), '(int $_)') # => [s(:int, 1), 1]
 ```
 
-### Fast.capture
+## Fast.capture
 
 To pick just the captures and ignore the nodes, use `Fast.capture`:
 
 ```ruby
 Fast.capture(code('a = 1'), '(int $_)') # => 1
 ```
-### Fast.replace
+## Fast.replace
 
 And if I want to refactor a code and use `delegate <attribute>, to: <object>`, try with replace:
 
@@ -303,7 +293,7 @@ Fast.replace_file('sample.rb', '({ lvasgn lvar } message )',
 
 To manipulate ruby files, some times you'll need some extra tasks.
 
-### Fast.ast_from_File(file)
+## Fast.ast_from_File(file)
 
 This method parses the code and load into a AST representation.
 
@@ -311,7 +301,7 @@ This method parses the code and load into a AST representation.
 Fast.ast_from_file('sample.rb')
 ```
 
-### Fast.search_file
+## Fast.search_file
 
 You can use `search_file` and pass the path for search for expressions inside
 files.
@@ -322,7 +312,7 @@ Fast.search_file('file.rb', expression)
 
 It's simple combination of `Fast.ast_from_file` with `Fast.search`.
 
-### Fast.ruby_files_from(arguments)
+## Fast.ruby_files_from(arguments)
 
 You'll be probably looking for multiple ruby files, then this method fetches
 all internal `.rb` files 
@@ -342,6 +332,38 @@ $ fast '(def match?)' lib/fast.rb
 
 - Use `-d` or `--debug` for enable debug mode.
 - Use `--ast` to output the AST instead of the original code
+- Use `--pry` to jump debugging the first result with pry
+- Use `-c` to search from code example
+- Use `-s` to search similar code
+
+```
+$ fast '(block (send nil it))' spec --pry
+```
+And inside pry session,  you can use `result` as the first result or `results`
+to use all occurrences found.
+
+```ruby
+results.map{|e|e.children[0].children[2]}
+# => [s(:str, "parses ... as Find"),
+# s(:str, "parses $ as Capture"),
+# s(:str, "parses quoted values as strings"),
+# s(:str, "parses {} as Any"),
+# s(:str, "parses [] as All"), ...]
+```
+
+Getting all `it` blocks without description:
+
+    $ fast '(block (send nil it (nil)) (args ) (!str)) ) )' spec
+
+```ruby
+# spec/fast_spec.rb:166
+it { expect(described_class).to be_match(s(:int, 1), '(...)') }
+# spec/fast_spec.rb:167
+it { expect(described_class).to be_match(s(:int, 1), '(_ _)') }
+# spec/fast_spec.rb:168
+it { expect(described_class).to be_match(code['"string"'], '(str "string")') }
+# ... more results
+```
 
 ## Experiments
 
@@ -406,3 +428,5 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/jonata
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
+
+See more on the [official documentation](https://jonatas.github.io/fast).

data/bin/fast

@@ -7,37 +7,58 @@ require 'fast'
 require 'coderay'
 
 arguments = ARGV
-pattern = arguments.shift
 show_sexp = arguments.delete('--ast')
 pry = arguments.delete('--pry')
+from_code = arguments.delete('--code') || arguments.delete('-c')
+similar = arguments.delete('--similar') || arguments.delete('-s')
 debug = arguments.delete('--debug') || arguments.delete('-d')
-files = Fast.ruby_files_from(*arguments || '.')
 
-pattern = Fast.expression(pattern)
+pattern = arguments.shift
+
+if similar || from_code
+  ast = Fast.ast(pattern)
+  if similar
+    puts "Looking for code similar to #{pattern}" if debug
+    pattern = Fast.expression_from(ast)
+  elsif from_code
+    pattern = ast.to_sexp
+    puts 'The generated expression from AST was:', pattern if debug
+  end
+end
+arguments << '.' if arguments.empty?
+
+files = Fast.ruby_files_from(*arguments)
 
-puts "Expression: #{pattern.map(&:to_s)}" if debug
+expression = Fast.expression(pattern)
+
+puts "Expression: #{expression.map(&:to_s).join(' ')}" if debug
 
 files.each do |file|
   results =
     if debug
-      Fast.debug { Fast.search_file(pattern, file) }
+      Fast.debug { Fast.search_file(expression, file) }
     else
       begin
-        Fast.search_file(pattern, file)
+        Fast.search_file(expression, file)
       rescue Parser::SyntaxError
-        puts "Ops! An error occurred trying to search in #{pattern.inspect} in #{file}", $ERROR_INFO, $ERROR_POSITION
+        if debug
+          puts "Ops! An error occurred trying to search in #{expression.inspect} in #{file}",
+               $ERROR_INFO,
+               $ERROR_POSITION
+        end
       end
     end
 
   next unless results
 
-  results.each do |node|
+  results.each do |result|
     next if result.nil? || result == []
+
     if pry
       require 'pry'
       binding.pry # rubocop:disable Lint/Debugger
     else
-      Fast.report(node, file: file, show_sexp: show_sexp)
+      Fast.report(result, file: file, show_sexp: show_sexp)
     end
   end
 end

data/docs/command_line.md

@@ -0,0 +1,112 @@
+# Command line
+
+It will also inject a executable named `fast` and you can use it to search and
+find code using the concept:
+
+```
+$ fast '(def match?)' lib/fast.rb
+```
+
+- Use `-d` or `--debug` for enable debug mode.
+- Use `--ast` to output the AST instead of the original code
+- Use `--pry` to jump debugging the first result with pry
+- Use `-c` to search from code example
+- Use `-s` to search similar code
+
+## `--pry`
+
+    $ fast '(block (send nil it))' spec --pry
+
+And inside pry session,  you can use `result` as the first result or `results`
+to use all occurrences found.
+
+```ruby
+results.map{|e|e.children[0].children[2]}
+# => [s(:str, "parses ... as Find"),
+# s(:str, "parses $ as Capture"),
+# s(:str, "parses quoted values as strings"),
+# s(:str, "parses {} as Any"),
+# s(:str, "parses [] as All"), ...]
+```
+
+Getting all `it` blocks without description:
+
+    $ fast '(block (send nil it (nil)) (args ) (!str)) ) )' spec
+
+```ruby
+# spec/fast_spec.rb:166
+it { expect(described_class).to be_match(s(:int, 1), '(...)') }
+# spec/fast_spec.rb:167
+it { expect(described_class).to be_match(s(:int, 1), '(_ _)') }
+# spec/fast_spec.rb:168
+it { expect(described_class).to be_match(code['"string"'], '(str "string")') }
+# ... more results
+```
+
+## `--debug`
+
+This option will print all matching details while validating each node.
+
+```
+$ echo 'object.method' > sample.rb
+$ fast -d '(send (send nil _) _)' sample.rb
+```
+
+It will bring details of the expression compiled and each node being validated:
+
+```
+Expression: f[send] [#<Fast::Find:0x00007f8c53047158 @token="send">, #<Fast::Find:0x00007f8c530470e0 @token="nil">, #<Fast::Find:0x00007f8c53047090 @token="_">] f[_]
+send == (send
+  (send nil :object) :method) # => true
+f[send] == (send
+  (send nil :object) :method) # => true
+send == (send nil :object) # => true
+f[send] == (send nil :object) # => true
+ ==  # => true
+f[nil] ==  # => true
+#<Proc:0x00007f8c53057af8@/Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/ffast-0.0.2/lib/fast.rb:25 (lambda)> == object # => true
+f[_] == object # => true
+[#<Fast::Find:0x00007f8c53047158 @token="send">, #<Fast::Find:0x00007f8c530470e0 @token="nil">, #<Fast::Find:0x00007f8c53047090 @token="_">] == (send nil :object) # => true
+#<Proc:0x00007f8c53057af8@/Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/ffast-0.0.2/lib/fast.rb:25 (lambda)> == method # => true
+f[_] == method # => true
+# sample.rb:1
+object.method
+```
+
+## `-s` for similarity
+
+Sometimes you want to search for some similar code like `(send (send (send nil _) _) _)` and we could simply say `a.b.c`.
+
+The option `-s` build an expression from the code ignoring final values.
+
+    $ echo 'object.method' > sample.rb
+    $ fast -s 'a.b' sample.rb
+
+```ruby
+# sample.rb:1
+object.method
+```
+
+See also [Code Similarity](simi)ilarity_tutorial.md) tutorial.
+
+# `-c` to search from code example
+
+You can search  for the exact expression with `-c`
+
+    $ fast -c 'object.method' sample.rb
+
+```ruby
+# sample.rb:1
+object.method
+```
+
+Combining with `-d`, in the header you can see the generated expression.
+
+```
+$ fast -d -c 'object.method' sample.rb | head -n 3
+
+The generated expression from AST was:
+(send
+  (send nil :object) :method)
+```
+

data/docs/experiments.md

@@ -0,0 +1,147 @@
+# Experiments
+
+Experiments allow us to play with AST and do some code transformation, execute
+some code and continue combining successful transformations.
+
+The major idea is try a new approach without any promise and if it works
+continue transforming the code.
+
+## Replace `FactoryBot#create` with `build_stubbed`.
+
+Let's look into the following spec example:
+
+```ruby
+describe "my spec" do
+  let(:user) { create(:user) }
+  let(:address) { create(:address) }
+  # ...
+end
+```
+
+Let's say we're amazed with `FactoryBot#build_stubbed` and want to build a small
+bot to make the changes in a entire code base. Skip some database
+touches while testing huge test suites are always a good idea.
+
+First we can hunt for the cases we want to find:
+
+```
+$ ruby-parse -e "create(:user)"
+(send nil :create
+  (sym :user))
+```
+
+Using `fast` in the command line to see real examples in the `spec` folder:
+
+```
+$ fast "(send nil create)" spec
+```
+
+If you don't have a real project but want to test, just create a sample ruby
+file with the code example above.
+
+Running it in a big codebase will probably find a few examples of blocks.
+
+The next step is build a replacement of each independent occurrence to use
+`build_stubbed` instead of create and combine the successful ones, run again and
+combine again, until try all kind of successful replacements combined.
+
+Considering we have the following code in `sample_spec.rb`:
+
+```ruby
+describe "my spec" do
+  let(:user) { create(:user) }
+  let(:address) { create(:address) }
+  # ...
+end
+```
+
+Let's create the experiment that will contain the nodes that are target to be
+executed and what we want to do when we find the node.
+
+```ruby
+experiment = Fast.experiment('RSpec/ReplaceCreateWithBuildStubbed') do
+  search '(send nil create)'
+  edit { |node| replace(node.loc.selector, 'build_stubbed') }
+end
+```
+
+If we use `Fast.replace_file` it will replace all occurrences in the same run
+and that's one of the motivations behind create the `ExperimentFile` class.
+
+Executing a partial replacement of the first occurrence:
+
+```ruby
+experiment_file = Fast::ExperimentFile.new('sample_spec.rb', experiment) }
+puts experiment_file.partial_replace(1)
+```
+
+The command will output the following code:
+
+```ruby
+describe "my spec" do
+  let(:user) { build_stubbed(:user) }
+  let(:address) { create(:address) }
+  # ...
+end
+```
+
+## Remove useless before block
+
+Imagine the following code sample:
+
+```ruby
+describe "my spec" do
+  before { create(:user) }
+  # ...
+  after { User.delete_all }
+end
+```
+
+And now, we can define an experiment that removes the entire code block and run
+the experimental specs.
+
+```ruby
+experiment = Fast.experiment('RSpec/RemoveUselessBeforeAfterHook') do
+  lookup 'spec'
+  search '(block (send nil {before after}))'
+  edit { |node| remove(node.loc.expression) }
+  policy { |new_file| system("bin/spring rspec --fail-fast #{new_file}") }
+end
+```
+
+To run the experiment you can simply say:
+
+```ruby
+experiment.run
+```
+
+Or drop the code into `experiments` folder and use the `fast-experiment` command
+line tool.
+
+    $ fast-experiment RSpec/RemoveUselessBeforeAfterHook spec
+ 
+## DSL
+
+- In the `lookup` you can pass files or folders.
+- The `search` contains the expression you want to match
+- With `edit` block you can apply the code change
+- And the `policy` is executed to check if the current change is valuable
+
+If the file contains multiple `before` or `after` blocks, each removal will
+occur independently and the successfull removals will be combined as a
+secondary change. The process repeates until find all possible combinations.
+
+See more examples in [experiments](experiments) folder.
+
+To run multiple experiments, use `fast-experiment` runner:
+
+```
+fast-experiment <experiment-names> <files-or-folders>
+```
+
+You can limit experiments or file escope:
+
+```
+fast-experiment RSpec/RemoveUselessBeforeAfterHook spec/models/**/*_spec.rb
+```
+