ffast 0.2.2 → 0.2.3

data/docs/shortcuts.md

@@ -1,323 +0,0 @@
-# Shortcuts
-
-Shortcuts are defined on a `Fastfile` inside any ruby project.
-
-!!!info "Use `~/Fastfile`"
-    You can also add one extra in your `$HOME` if you want to have something loaded always.
-
-By default, the command line interface does not load any `Fastfile` if the
-first param is not a shortcut. It should start with `.`.
-
-I'm building several researches and I'll make the examples open here to show
-several interesting cases in action.
-
-## List your fast shortcuts
-
-As the interface is very rudimentar, let's build a shortcut to print what
-shortcuts are available. This is a good one to your `$HOME/Fastfile`:
-
-```ruby
-# List all shortcut with comments
-Fast.shortcut :shortcuts do
-  fast_files.each do |file|
-    lines = File.readlines(file).map{|line|line.chomp.gsub(/\s*#/,'').strip}
-    result = capture_file('(send ... shortcut $(sym _', file)
-    result = [result] unless result.is_a?Array
-    result.each do |capture|
-      target = capture.loc.expression
-      puts "fast .#{target.source[1..-1].ljust(30)} # #{lines[target.line-2]}"
-    end
-  end
-end
-```
-
-And using it on `fast` project that loads both `~/Fastfile` and the Fastfile from the project:
-
-```
-fast .version       # Let's say you'd like to show the version that is over the version file
-fast .parser        # Simple shortcut that I used often to show how the expression parser works
-fast .bump_version  # Use `fast .bump_version` to rewrite the version file
-fast .shortcuts     # List all shortcut with comments
-```
-
-## Search for references
-
-I always miss bringing something simple as `grep keyword` where I can leave a simple string and it can
-search in all types of nodes and report interesting things about it.
-
-Let's consider a very flexible search that can target any code related to some
-keyword. Considering that we're talking about code indentifiers:
-
-
-```ruby
-# Search all references about some keyword or regular expression
-Fast.shortcut(:ref) do
-  require 'fast/cli'
-  Kernel.class_eval do
-    def matches_args? identifier
-      search = ARGV.last
-      regex = Regexp.new(search, Regexp::IGNORECASE)
-      case identifier
-      when Symbol, String
-        regex.match?(identifier) || identifier.to_s.include?(search)
-      when Astrolabe::Node
-        regex.match?(identifier.to_sexp)
-      end
-    end
-  end
-  pattern = <<~FAST
-    {
-      ({class def sym str} #matches_args?)'
-      ({const send} nil #matches_args?)'
-    }
-  FAST
-  Fast::Cli.run!([pattern, '.', '--parallel'])
-end
-```
-
-## Rails: Show validations from models
-
-If the shortcut does not define a block, it works as a holder for arguments from
-the command line.
-
-Let's say you always use `fast "(send nil {validate validates})" app/models` to
-check validations in the models. You can define a shortcut to hold the args and
-avoid retyping long lines:
-
-```ruby
-# Show validations from app/models
-Fast.shortcut(:validations, "(send nil {validate validates})", "app/models")
-```
-And you can reuse the search with the shortcut starting with a `.`:
-
-```
-fast .validations
-```
-And it will also accept params if you want to filter a specific file:
-
-```
-fast .validations app/models/user.rb
-```
-
-!!! info "Note that you can also use flags in the command line shortcuts"
-
-    Let's say you also want to use `fast --headless` you can add it to the params:
-
-    > Fast.shortcut(:validations, "(send nil {validate validates})", "app/models", "--headless")
-
-## Automated Refactor: Bump version
-
-Let's start with a [real usage](https://github.com/jonatas/fast/blob/master/Fastfile#L20-L34)
-to bump a new version of the gem.
-
-```ruby
-Fast.shortcut :bump_version do
-  rewrite_file('(casgn nil VERSION (str _)', 'lib/fast/version.rb') do |node|
-    target = node.children.last.loc.expression
-    pieces = target.source.split('.').map(&:to_i)
-    pieces.reverse.each_with_index do |fragment, i|
-      if fragment < 9
-        pieces[-(i + 1)] = fragment + 1
-        break
-      else
-        pieces[-(i + 1)] = 0
-      end
-    end
-    replace(target, "'#{pieces.join('.')}'")
-  end
-end
-```
-
-And then the change is done in the `lib/fast/version.rb`:
-
-```diff
-module Fast
--  VERSION = '0.1.6'
-+  VERSION = '0.1.7'
-end
-```
-
-## RSpec: Find unused shared contexts
-
-If you build shared contexts often, probably you can forget some left overs.
-
-The objective of the shortcut is find leftovers from shared contexts.
-
-First, the objective is capture all names of the `RSpec.shared_context` or
- `shared_context` declared in the `spec/support` folder.
-
-```ruby
-Fast.capture_all('(block (send {nil,_} shared_context (str $_)))', Fast.ruby_files_from('spec/support'))
-```
-
-Then, we need to check all the specs and search for `include_context` usages to
-confirm if all defined contexts are being used:
-
-```ruby
-specs = Fast.ruby_files_from('spec').select{|f|f !~ %r{spec/support/}}
-Fast.search_all("(send nil include_context (str #register_usage)", specs)
-```
-
-Note that we created a new reference to `#register_usage` and we need to define the method too:
-
-
-```ruby
-@used = []
-def register_usage context_name
-	@used << context_name
-end
-```
-
-Wrapping up everything in a shortcut:
-
-```ruby
-# Show unused shared contexts
-Fast.shortcut(:unused_shared_contexts) do
-  puts "Checking shared contexts"
-  Kernel.class_eval do
-    @used = []
-    def register_usage context_name
-      @used << context_name
-    end
-    def show_report! defined_contexts
-      unused = defined_contexts.values.flatten - @used
-      if unused.any?
-        puts "Unused shared contexts", unused
-      else
-        puts "Good job! all the #{defined_contexts.size} contexts are used!"
-      end
-    end
-  end
-  specs = ruby_files_from('spec/').select{|f|f !~ %r{spec/support/}}
-  search_all("(send nil include_context (str #register_usage)", specs)
-  defined_contexts = capture_all('(block (send {nil,_} shared_context (str $_)))', ruby_files_from('spec'))
-  Kernel.public_send(:show_report!, defined_contexts)
-end
-```
-
-!!! faq "Why `#register_usage` is defined on the `Kernel`?"
-    Yes! note that the `#register_usage` was forced to be inside `Kernel`
-    because of the `shortcut` block that takes the `Fast` context to be easy
-    to access in the default functions. As I can define multiple shortcuts
-    I don't want to polute my Kernel module with other methods that are not useful.
-
-
-## RSpec: Remove unused let
-
-!!! hint "First shortcut with experiments"
-    If you're not familiar with automated experiments, you can read about it [here](/experiments).
-
-The current scenario is similar in terms of search with the previous one, but more advanced
-because we're going to introduce automated refactoring.
-
-The idea is simple, if it finds a `let` in a RSpec scenario that is not referenced, it tries to experimentally remove the `let` and run the tests:
-
-```ruby
-# Experimental remove `let` that are not referenced in the spec
-Fast.shortcut(:exp_remove_let) do
-  require 'fast/experiment'
-  Kernel.class_eval do
-    file = ARGV.last
-
-    defined_lets = Fast.capture_file('(block (send nil let (sym $_)))', file).uniq
-    @unreferenced= defined_lets.select do |identifier|
-      Fast.search_file("(send nil #{identifier})", file).empty?
-    end
-
-    def unreferenced_let?(identifier)
-      @unreferenced.include? identifier
-    end
-  end
-
-  experiment('RSpec/RemoveUnreferencedLet') do
-    lookup ARGV.last
-    search '(block (send nil let (sym #unreferenced_let?)))'
-    edit { |node| remove(node.loc.expression) }
-    policy { |new_file| system("bundle exec rspec --fail-fast #{new_file}") }
-  end.run
-end
-```
-
-And it will run with a single file from command line:
-
-```
-fast .exp_remove_let spec/my_file_spec.rb
-```
-
-## FactoryBot: Replace `create` with `build_stubbed`
-
-For performance reasons, if we can avoid touching the database the test will
-always be faster.
-
-```ruby
-# Experimental switch from `create` to `build_stubbed`
-Fast.shortcut(:exp_build_stubbed) do
-  require 'fast/experiment'
-  Fast.experiment('FactoryBot/UseBuildStubbed') do
-  lookup ARGV.last
-    search '(send nil create)'
-    edit { |node| replace(node.loc.selector, 'build_stubbed') }
-    policy { |new_file| system("bundle exec rspec --fail-fast #{new_file}") }
-  end.run
-end
-```
-## RSpec: Use `let_it_be` instead of `let`
-
-The `let_it_be` is a simple helper from
-[TestProf](https://test-prof.evilmartians.io/#/let_it_be) gem that can speed up
-the specs by caching some factories using like a `before_all` approach.
-
-This experiment hunts  for `let(...) { create(...) }` and switch the `let` to
-`let_it_be`:
-
-```ruby
-# Experimental replace `let(_)`  with `let_it_be` case it calls `create` inside the block
-Fast.shortcut(:exp_let_it_be) do
-  require 'fast/experiment'
-  Fast.experiment('FactoryBot/LetItBe') do
-    lookup ARGV.last
-    search '(block (send nil let (sym _)) (args) (send nil create))'
-    edit { |node| replace(node.children.first.loc.selector, 'let_it_be') }
-    policy { |new_file| system("bin/spring rspec --fail-fast #{new_file}") }
-  end.run
-end
-```
-
-## RSpec: Remove `before` or `after` blocks
-
-From time to time, we forget some left overs like `before` or `after` blocks
-that even removing from the code, the tests still passes. This experiment
-removes the before/after blocks and check if the test passes.
-
-```ruby
-# Experimental remove `before` or `after` blocks.
-Fast.shortcut(:exp_remove_before_after) do
-  require 'fast/experiment'
-  Fast.experiment('RSpec/RemoveBeforeAfter') do
-    lookup ARGV.last
-    search '(block (send nil {before after}))'
-    edit { |node| remove(node.loc.expression) }
-    policy { |new_file| system("bin/spring rspec --fail-fast #{new_file}") }
-  end.run
-end
-```
-
-## RSpec: Show message chains
-
-I often forget the syntax and need to search for message chains on specs, so I
-created an shortcut for it.
-
-```ruby
-# Show RSpec message chains
-Fast.shortcut(:message_chains, '^^(send nil receive_message_chain)', 'spec')
-```
-
-## RSpec: Show nested assertions
-
-I love to use nested assertions and I often need examples to refer to them:
-
-```ruby
-# Show RSpec nested assertions with .and
-Fast.shortcut(:nested_assertions, '^^(send ... and)', 'spec')
-```
-

data/docs/similarity_tutorial.md

@@ -1,176 +0,0 @@
-# Research for code similarity
-
-This is a small tutorial to explore code similarity.
-
-Check the code example [here](https://github.com/jonatas/fast/blob/master/examples/similarity_research.rb).
-
-The major idea is register all expression styles and see if we can find some
-similarity between the structures.
-
-First we need to create a function that can analyze AST nodes and extract a
-pattern from the expression.
-
-The expression needs to generalize final node values and recursively build a
-pattern that can be used as a search expression.
-
-```ruby
-def expression_from(node)
-  case node
-  when Parser::AST::Node
-    if node.children.any?
-      children_expression = node.children
-        .map(&method(:expression_from))
-        .join(' ')
-      "(#{node.type} #{children_expression})"
-    else
-      "(#{node.type})"
-    end
-  when nil, 'nil'
-    'nil'
-  when Symbol, String, Integer
-    '_'
-  when Array, Hash
-    '...'
-  else
-    node
-  end
-end
-```
-
-The pattern generated only flexibilize the search allowing us to group similar nodes.
-
-Example:
-
-```ruby
-expression_from(code['1']) # =>'(int _)'
-expression_from(code['nil']) # =>'(nil)'
-expression_from(code['a = 1']) # =>'(lvasgn _ (int _))'
-expression_from(code['def name; person.name end']) # =>'(def _ (args) (send (send nil _) _))'
-```
-
-The current method can translate all kind of expressions and the next step is
-observe some specific node types and try to group the similarities
-using the pattern generated.
-
-```ruby
-Fast.search_file('class', 'lib/fast.rb')
-```
-Capturing the constant name and filtering only for symbols is easy and we can
-see that we have a few classes defined in the the same file.
-
-```ruby
-Fast.search_file('(class (const nil $_))','lib/fast.rb').grep(Symbol)
-=> [:Rewriter,
- :ExpressionParser,
- :Find,
- :FindString,
- :FindWithCapture,
- :Capture,
- :Parent,
- :Any,
- :All,
- :Not,
- :Maybe,
- :Matcher,
- :Experiment,
- :ExperimentFile]
-```
-
-The idea of this inspecton is build a proof of concept to show the similarity
-of matcher classes because they only define a `match?` method.
-
-```ruby
-patterns = Fast.search_file('class','lib/fast.rb').map{|n|Fast.expression_from(n)}
-```
-
-A simple comparison between the patterns size versus `.uniq.size` can proof if
-the idea will work.
-
-```ruby
-patterns.size == patterns.uniq.size
-```
-
-It does not work for the matcher cases but we can go deeper and analyze all
-files required by bundler.
-
-```ruby
-similarities = {}
-Gem.find_files('*.rb').each do |file|
-  Fast.search_file('{block send if while case def defs class module}', file).map do |n|
-    key = Fast.expression_from(n)
-    similarities[key] ||= Set.new
-    similarities[key] << file
-  end 
-end
-similarities.delete_if {|k,v|v.size < 2}
-```
-The similarities found are the following:
-
-```ruby
-{"(class (const nil _) (const nil _) nil)"=>
-  #<Set: {"/Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/parallel-1.12.1/lib/parallel.rb",
-   "/Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/method_source-0.9.0/lib/method_source.rb",
-   "/Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/rdoc.rb",
-   "/Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/irb.rb",
-   "/Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/tsort.rb"}>,
- "(class (const nil _) nil nil)"=>#<Set: {"/Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/ripper.rb", "/Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/cgi.rb"}>}
-```
-
-And now we can test the expression using the command line tool through the files
-and observe the similarity:
-
-```
-⋊> ~ fast "(class (const nil _) (const nil _) nil)" /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/parallel-1.12.1/lib/parallel.rb /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/method_source-0.9.0/lib/method_source.rb /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/rdoc.rb /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/irb.rb /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/tsort.rb
-```
-
-Output:
-
-```ruby
-# /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/parallel-1.12.1/lib/parallel.rb:8
-class DeadWorker < StandardError
-end
-# /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/parallel-1.12.1/lib/parallel.rb:11
-class Break < StandardError
-end
-# /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/parallel-1.12.1/lib/parallel.rb:14
-class Kill < StandardError
-end
-# /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/method_source-0.9.0/lib/method_source.rb:16
-class SourceNotFoundError < StandardError; end
-# /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/rdoc.rb:63
-class Error < RuntimeError; end
-# /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/irb.rb:338
-class Abort < Exception;end
-# /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/tsort.rb:125
-class Cyclic < StandardError
-end
-```
-
-It works and now we can create a method to do what the command line tool did, 
-grouping the patterns and inspecting the occurrences.
-
-```ruby
-def similarities.show pattern
-  files = self[pattern]
-  files.each do |file|
-    nodes = Fast.search_file(pattern, file)
-    nodes.each do |result|
-      Fast.report(result, file: file)
-    end
-  end
-end
-```
-
-And calling the method exploring some "if" similarities, it prints the following
-results:
-
-```ruby
-similarities.show "(if (send (const nil _) _ (lvar _)) nil (return (false)))"
-# /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/resolv.rb:1248
-return false unless Name === other
-# /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/fileutils.rb:138
-return false unless File.exist?(new)
-# /Users/jonatasdp/.rbenv/versions/2.5.1/lib/ruby/2.5.0/matrix.rb:1862
-return false unless Vector === other
-```
-