ffast 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7d9179d0dbc56cc0f493cdbff51cd926b4476c37
-  data.tar.gz: 953cef108b8207d8d83aa16681f8f31e3c79b8f8
+  metadata.gz: 238c006c217b8838c23488cbfafe15c3e694d69a
+  data.tar.gz: '095e4dfdba32adf0ddf52da166c27a93c8bbd3bb'
 SHA512:
-  metadata.gz: 25b1bb7d048b2784a8127b60841ed8946495bacace7ad0caa8acc6f256aa1c2b3116491898d8b276321a0c5db847d350763c1bc18ef88c2cfaee4b6fa7a8c682
-  data.tar.gz: e8e7e051223d4b1c2bb77d5d44c742518f38c7d9bf75c49342dfa495c4c5252e72ed6890d9c6d68c6faf531e1e1166391ae0cd79f20162ed81df77036bd14413
+  metadata.gz: 73ce257e59e1bd96cbc62d4b23225cd50f5bfa551ca64eeb38da4693bc832b14203d2335d6e55e389b74fd5feba1e164ed2f1adbcdbeca0a14676115e1df5c02
+  data.tar.gz: 3133c3f337da981e728ab42ed9bf61eafc907715c3c6bb7c210ff38d6a6c73d3e87cf88625d8cac4dcfa648d3f909b3e6625a502d96c9a2316e04436086c7f8f

data/.rubocop.yml

@@ -0,0 +1,37 @@
+# This is the configuration used to check the rubocop source code.
+
+require:
+  - rubocop-rspec
+
+AllCops:
+  Exclude:
+    - 'tmp/**/*'
+    - 'examples/*'
+  TargetRubyVersion: 2.3
+
+Metrics/LineLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Lint/InterpolationCheck:
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/MethodLength:
+  CountComments: false  # count full line comments?
+  Max: 12
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: 'indented'
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/ExampleLength:
+  Max: 20

data/.travis.yml

@@ -3,3 +3,12 @@ language: ruby
 rvm:
   - 2.3.3
 before_install: gem install bundler -v 1.13.7
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT
+script:
+  - bundle exec rubocop
+  - bundle exec rspec

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in fast.gemspec

data/Guardfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # A sample Guardfile
 # More info at https://github.com/guard/guard#readme
 
@@ -19,8 +21,8 @@ guard 'livereload' do
   watch(%r{lib/.+\.rb$})
 end
 
-guard :rspec, cmd: "bundle exec rspec" do
-  require "guard/rspec/dsl"
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
   dsl = Guard::RSpec::Dsl.new(self)
 
   # Feel free to open issues for suggestions and improvements

data/README.md

@@ -4,21 +4,33 @@
 
 Fast is a "Find AST" tool to help you search in the code abstract syntax tree.
 
-It's inspired on [RuboCop Node Pattern](https://github.com/bbatsov/rubocop/blob/master/lib/rubocop/node_pattern.rb).
+Ruby allow us to do the same thing in a few ways then it's hard to check
+how the code is written.
 
-To learn more about how AST works, you can install `ruby-parse` and check how is the AST of
-your current code.
+## Syntax for find in AST
 
-`ruby-parse my-file.rb`
+The current version cover the following elements:
 
-It will output the AST representation.
+- `()` to represent a **node** search
+- `{}` is for **any** matches like **union** conditions with **or** operator
+- `[]` is for **all** matches like **intersect** conditions with **and** operator
+- `$` is for **capture** current expression
+- `_` is **something** not nil
+- `nil` matches exactly **nil**
+- `...` is a **node** with children
+- `^` is to get the **parent node** of an expression
+- `?` is for **maybe**
+- `\1` to use the first **previous captured** element
+- `""` surround the value with double quotes to match literal strings
+
+The syntax is inspired on [RuboCop Node Pattern](https://github.com/bbatsov/rubocop/blob/master/lib/rubocop/node_pattern.rb).
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'fast'
+gem 'ffast'
 ```
 
 And then execute:
@@ -27,44 +39,119 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install fast
+    $ gem install ffast
 
 ## How it works
 
 The idea is search in abstract tree using a simple expression build with an array:
 
-The following code:
+A simple integer in ruby:
 
 ```ruby
-a += 1
+1
 ```
 
-Generates the following AST representation:
+Is represented by:
 
 ```ruby
-ast =
-  s(:op_asgn,
-    s(:lvasgn, :a),
-    :+,
-    s(:int, 1)
-  )
+s(:int, 1)
 ```
 
 Basically `s` represents `Parser::AST::Node` and the node has a `#type` and `#children`.
 
-You can try to search by nodes that is using `:op_asgn` with some children using `...`:
+```ruby
+def s(type, *children)
+  Parser::AST::Node.new(type, children)
+end
+```
+
+A local variable assignment:
+
+```ruby
+value = 42
+```
+
+Can be represented with:
+
+```ruby
+ast = s(:lvasgn, :value, s(:int, 42))
+```
+
+Now, lets find local variable named `value` with an value `42`:
+
+```ruby
+Fast.match?(ast, '(lvasgn value (int 42))') # true
+```
+
+Lets abstract a bit and allow some integer value using `_` as a shortcut:
+
+```ruby
+Fast.match?(ast, '(lvasgn value (int _))') # true
+```
+
+Lets abstract more and allow float or integer:
+
+```ruby
+Fast.match?(ast, '(lvasgn value ({float int} _))') # true
+```
+
+Or combine multiple assertions using `[]` to join conditions:
+
+```ruby
+Fast.match?(ast, '(lvasgn value ([!str !hash !array] _))') # true
+```
+
+Matches all local variables not string **and** not hash **and** not array.
+
+We can match "a node with children" using `...`:
+
+```ruby
+Fast.match?(ast, '(lvasgn value ...)') # true
+```
+
+You can use `$` to capture a node:
 
 ```ruby
-Fast.match?(ast, [:op_asgn, '...']) # => true
+Fast.match?(ast, '(lvasgn value $...)') # => [s(:int, 42)]
 ```
 
-You can also check if the element is not nil with `_`:
+Or match whatever local variable assignment combining both `_` and `...`:
 
 ```ruby
-Fast.match?(ast, [:op_asgn, '_', '_', '_'])) # => true
+Fast.match?(ast, '(lvasgn _ ...)') # true
 ```
 
-You can go deeply with the arrays. Let's suppose we have a hardcore call to
+You can also use captures in any levels you want:
+
+```ruby
+Fast.match?(ast, '(lvasgn $_ $...)') # [:value, s(:int, 42)]
+```
+
+Keep in mind that `_` means something not nil and `...` means a node with
+children.
+
+Then, if do you get a method declared:
+
+```ruby
+def my_method
+  call_other_method
+end
+```
+It will be represented with the following structure:
+
+```ruby
+ast =
+  s(:def, :my_method,
+    s(:args),
+    s(:send, nil, :call_other_method))
+```
+
+Keep an eye on the node `(args)`.
+
+Then you know you can't use `...` but you can match with `(_)` to match with
+such case.
+
+Let's test a few other examples. You can go deeply with the arrays. Let's suppose we have a hardcore call to
 `a.b.c.d` and the following AST represents it:
 
 ```ruby
@@ -78,7 +165,8 @@ ast =
     :d)
 ```
 
-You can search using sub-arrays in the same way:
+You can search using sub-arrays with **pure values**, or **shortcuts** or
+**procs**:
 
 ```ruby
 Fast.match?(ast, [:send, [:send, '...'], :d]) # => true
@@ -86,11 +174,20 @@ Fast.match?(ast, [:send, [:send, '...'], :c]) # => false
 Fast.match?(ast, [:send, [:send, [:send, '...'], :c], :d]) # => true
 ```
 
-It also knows how to parse strings:
+Shortcuts like `...` and `_` are just literals for procs. Then you can use
+procs directly too:
 
 ```ruby
-expression = '(send (send (send (send nil $_) $_) $_) $_)'
-Fast.match?(ast, expression)) # => [:a, :b, :c, :d]
+Fast.match?(ast, [:send, [ -> (node) { node.type == :send }, [:send, '...'], :c], :d]) # => true
+```
+
+And also work with expressions:
+
+```ruby
+Fast.match?(
+  ast,
+  '(send (send (send (send nil $_) $_) $_) $_)'
+) # => [:a, :b, :c, :d]
 ```
 
 If something does not work you can debug with a block:
@@ -106,22 +203,198 @@ int == (int 1) # => true
 1 == 1 # => true
 ```
 
-## Search in files
+## Use previous captures in search
+
+Imagine you're looking for a method that is just delegating something to
+another method, like:
+
+```ruby
+def name
+  person.name
+end
+```
+
+This can be represented as the following AST:
+
+```
+(def :name
+  (args)
+  (send
+    (send nil :person) :name))
+```
+
+Then, let's build a search for methods that calls an attribute with the same
+name:
+
+```ruby
+Fast.match?(ast,'(def $_ ... (send (send nil _) \1))') # => [:name]
+```
+
+### 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.
+
+```ruby
+Fast.search(code('a = 1'), '(int _)') # => s(:int, 1)
+```
+
+If you use captures, it returns the node and the captures respectively:
+
+```ruby
+Fast.search(code('a = 1'), '(int $_)') # => [s(:int, 1), 1]
+```
+
+### Fast.capture
+
+To pick just the captures and ignore the nodes, use `Fast.capture`:
+
+```ruby
+Fast.capture(code('a = 1'), '(int $_)') # => 1
+```
+### Fast.replace
+
+And if I want to refactor a code and use `delegate <attribute>, to: <object>`, try with replace:
+
+```ruby
+Fast.replace ast,
+  '(def $_ ... (send (send nil $_) \1))',
+  -> (node, captures) {
+    attribute, object = captures
+    replace(
+      node.location.expression,
+      "delegate :#{attribute}, to: :#{object}"
+    )
+  }
+```
+
+### Replacing file
+
+Now let's imagine we have real files like `sample.rb` with the following code:
+
+```ruby
+def good_bye
+  message = ["good", "bye"]
+  puts message.join(' ')
+end
+```
+
+And we decide to remove the `message` variable and put it inline with the `puts`.
+
+Basically, we need to find the local variable assignment, store the value in
+memory. Remove the assignment expression and use the value where the variable
+is being called.
+
+```ruby
+assignment = nil
+Fast.replace_file('sample.rb', '({ lvasgn lvar } message )',
+  -> (node, _) {
+    if node.type == :lvasgn
+      assignment = node.children.last
+      remove(node.location.expression)
+    elsif node.type == :lvar
+      replace(node.location.expression, assignment.location.expression.source)
+    end
+  }
+)
+```
+
+## Other useful functions
+
+To manipulate ruby files, some times you'll need some extra tasks.
+
+### Fast.ast_from_File(file)
+
+This method parses the code and load into a AST representation.
+
+```ruby
+Fast.ast_from_file('sample.rb')
+```
+
+### Fast.search_file
+
+You can use `search_file` and pass the path for search for expressions inside
+files.
+
+```ruby
+Fast.search_file('file.rb', expression)
+```
+
+It's simple combination of `Fast.ast_from_file` with `Fast.search`.
+
+### Fast.ruby_files_from(arguments)
+
+You'll be probably looking for multiple ruby files, then this method fetches
+all internal `.rb` files 
+
+```ruby
+Fast.ruby_files_from(['lib']) # => ["lib/fast.rb"]
+```
+
+## `fast` in the command line
 
 It will also inject a executable named `fast` and you can use it to search and
-find code by this kind of expression
+find code using the concept:
 
 ```
-$ fast '(:def :match_node? _ )' lib/fast.rb                                                                                                              20:36:21
+$ 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
 
+## Experiments
+
+You can define experiments and build experimental research to improve some code in
+an automated way.
+
+Let's create an experiment to try to remove `before` or `after` blocks
+and run specs. If the spec pass without need the hook, the hook is useless.
+
+```ruby
+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
+```
+
+- 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
+```
+
 ## 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.
 
+On the console we have a few functions like `s` and `code` to make it easy ;)
+
+$ bin/console
+
+```ruby
+code("a = 1") # => s(:lvasgn, s(:int, 1))
+```
+
 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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing