reek 6.0.1 → 6.0.5

data/docs/Feature-Envy.md

@@ -1,93 +0,0 @@
-# Feature Envy
-
-## Introduction
-
-_Feature Envy_ occurs when a code fragment references another object more often than it references itself, or when several clients do the same series of manipulations on a particular type of object.
-
-_Feature Envy_ reduces the code's ability to communicate intent: code that "belongs" on one class but which is located in another can be hard to find, and may upset the "System of Names" in the host class.
-
-_Feature Envy_ also affects the design's flexibility: A code fragment that is in the wrong class creates couplings that may not be natural within the application's domain, and creates a loss of cohesion in the unwilling host class.
-
-_Feature Envy_ often arises because it must manipulate other objects (usually its arguments) to get them into a useful form, and one force preventing them (the arguments) doing this themselves is that the common knowledge lives outside the arguments, or the arguments are of too basic a type to justify extending that type. Therefore there must be something which 'knows' about the contents or purposes of the arguments.  That thing would have to be more than just a basic type, because the basic types are either containers which don't know about their contents, or they are single objects which can't capture their relationship with their fellows of the same type. So, this thing with the extra knowledge should be reified into a class, and the utility method will most likely belong there.
-
-## Example
-
-Running Reek on:
-
-```Ruby
-class Warehouse
-  def sale_price(item)
-    (item.price - item.rebate) * @vat
-  end
-end
-```
-
-would report:
-
-```Bash
-Warehouse#sale_price refers to item more than self (FeatureEnvy)
-```
-
-since this:
-
-```Ruby
-(item.price - item.rebate)
-```
-
-belongs to the Item class, not the Warehouse.
-
-## Current Support in Reek
-
-_Feature Envy_ reports any method that refers to self less often than it refers to (ie. send messages to) some other object.
-
-## Edge cases
-
-Be aware that there are some edge cases like this code:
-
-```Ruby
-class Foo
-  def initialize
-    @map = {
-      a: ->(arg) { arg.css('table') },
-      b: ->(arg) { arg.css('div') },
-      c: ->(arg) { arg.css('span') }
-    }
-  end
-end
-```
-
-Reek cannot reliably detect that each call's receiver is a different arg and will report:
-
-```
-  [4, 5, 6]:FeatureEnvy: Foo#initialize refers to 'arg' more than self (maybe move it to another class?)
-```
-  
-If you're running into this problem you can disable this smell detector for this method either via
-configuration:
-
-```Yaml
----
-FeatureEnvy:
-  exclude:
-    - 'Foo#bar'
-```
-
-or via source code comment:
-
-```Ruby
-class Foo
-  # :reek:FeatureEnvy
-  def initialize
-    @map = {
-    # ....
-  end
-end
-```
-
-## Differences to _Utility Function_
-
-_Feature Envy_ is only triggered if there are some references to self and _[Utility Function](Utility-Function.md)_ is triggered if there are no references to self.
-
-## Configuration
-
-_Feature Envy_ supports the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/How-To-Write-New-Detectors.md

@@ -1,132 +0,0 @@
-## How to write new detectors
-
-### Outline what you have in mind
-
-Before starting to code you should discuss the overall idea for your new smell detector with
-us in a corresponding github issue.
-We all should have a solid understanding of what this detector actually reports, the edgecases
-it covers and the overall rationale behind it.
-
-### Structure
-
-All smell detectors reside in `lib/reek/smell_detectors` and have the following base structure:
-
-```Ruby
-require_relative 'base_detector'
-require_relative 'smell_warning'
-
-module Reek
-  module SmellDetectors
-    #
-    # Here goes your introduction for this detector.
-    #
-    # See {file:docs/Your-Detector.md} for details.
-    class YourDetector < BaseDetector
-      def self.contexts
-        [:class] # In case you're operating on class contexts only - just an example.
-      end
-
-      #
-      # Here you should document what you expect the detector's context to look
-      # like.
-      #
-      # @return [Array<SmellWarning>]
-      #
-      def sniff
-        # "found_smells" below is just an abstraction for
-        # "find the smells in question" and iterate over them.
-        # This can just be a method but it can also be a more sophisticated set up.
-        # Check out other smell detectors to get a feeling for what to do here.
-        found_smells.map do |smell|
-          # "smell_warning" is defined in BaseDetector and should be used by you
-          # to construct smell warnings
-          smell_warning(
-            lines: [], # lines on which the smell was detected
-            message: "...", # the message that is printed on STDOUT
-            # whatever you interpolate into the "message" should go into
-            # parameters below - if you do not interpolate anything you
-            # can omit this
-            parameters: { })
-          end
-        end
-      end
-
-      private
-
-      # Here goes everything you need for finding smells.
-    end
-  end
-end
-```
-
-For your detector to be properly loaded you need to require it in `lib/reek/smell_detectors.rb` as well.
-
-### defaults.reek.yml
-
-After you ran
-
-```
-bundle exec rake
-```
-
-for the first time with your shiny new detector in place the `docs/defaults.reek.yml`
-file should have been updated automatically. Make sure you don't forget to check
-in those changes as well.
-
-### Documentation
-
-* Above every `SmellDetector::sniff` method it should be documented what the expected AST is
-* Every detector should have a separate documentation page in /docs. You can
-  take any arbitrary existing smell detector documentation page as template (since
-  they all have the same structure already)
-* The detector should be listed under [Code Smells](docs/Code-Smells.md)
-* Depending on what your detector does it might make sense to add it to other doc pages as
-  well e.g. [Simulated Polymorphism](docs/Simulated-Polymorphism.md)
-
-### Rspec examples
-
-All smell detector specs start out with 2 generic examples like below - the second one
-only if it makes sense.
-Here's what it looks like for `UncommunicativeVariableName`:
-
-```Ruby
-it 'reports the right values' do
-  src = <<-RUBY
-    def alfa
-      bravo = 5
-    end
-  RUBY
-
-  expect(src).to reek_of(:UncommunicativeVariableName,
-                         lines:   [2],
-                         context: 'alfa',
-                         message: "has the variable name 'bravo'",
-                         source:  'string',
-                         name:    'bravo')
-end
-
-it 'does count all occurences' do
-  src = <<-RUBY
-    def alfa
-      bravo = 3
-      charlie = 7
-    end
-  RUBY
-
-  expect(src).to reek_of(:UncommunicativeVariableName,
-                         lines: [2],
-                         name:  'bravo')
-  expect(src).to reek_of(:UncommunicativeVariableName,
-                         lines: [3],
-                         name:  'charlie')
-end
-```
-
-The following examples should then cover the detector specific features.
-
-### Cucumber features
-
-We are trying to write as few Cucumber features as possible.
-Normally, there should be no need to write a new feature for a new smell detector.
-If you feel like this is necessary in this case, please discuss this with us via
-github issue or in your work-in-progress pull request before doing anything.

data/docs/How-reek-works-internally.md

@@ -1,114 +0,0 @@
-# How Reek works internally
-
-
-## The big picture
-
-```
-["class C; end" | reek]            [reek lib/*.rb]                             [expect(files).not_to reek_of(:LargeClass)]
-             \                            |                                                          |
-              \                           |                                                          |
-               \                          |                                                          |
-                \             creates a   |                                                          |
-                 \                        |                                                          |
-                  \                       |                                                          |
-                   \                      |                                                          |
-                    \                     |                                                          |
-                     \---------- Application (cli/application.rb) +                                  |
-                                    Options (cli/options)                                            |
-                                          |                                                          |
-                                          |                                                          |
-                                          |                                                          |
-                                          |                                                          |
-                              creates a   |                                                          |
-                                          |                                                          |
-                                          |                                                          |
-                                          |                                                          |
-                                          |                                                          |
-                                ReekCommand (cli/reek_command)                                       |
-                                * uses a reporter (report/report)                                    |
-                                * uses a SourceLocator (source/source_locator)                       |
-                                /         |         \                                                |
-                               /          |          \                                               |
-                              /           |           \                                              |
-                        Source          Source      Source (source/source_code)                      |
-                          |               |            |                                             |
-                          |               |            |                                             |
-                          |               |            |                                             |
-                      Examiner            |         Examiner                                         |
-                                          |                                                          |
-                                          |                                                          |
-                                      Examiner (core/examiner)  --------------------------------------
-                                  * generates the AST out of the given source
-                                  * adorns the generated AST via a TreeDresser (core/tree_dresser)
-                                  * initializes a DetectorRepository with all relevant smells (smells/detector_repository)
-                                  * builds a tree of Contexts using ContextBuilder
-                                  * tells the DetectorRepository above to run each of its smell detectors above on each of the contexts
-                                  /       |       \
-                                 /        |        \
-                                /         |         \
-                    UtilityFunction   FeatureEnvy   TooManyMethods
-                                \         |         /
-                                 \        |        /
-                                  \       |       /
-                                   DetectorRepository
-                                          |
-                                          |
-                                          |
-                                    Application output
-
-## A closer look at how an Examiner works
-
-The core foundation of Reek and its API is the Examiner.
-As you can see above, the Examiner is run for every source it gets passed and then runs the configured SmellDetectors.
-The overall workflow is like this:
-
-        Examiner
-            |
-            |
-            |
-        Initialize DetectorRepository only with eligible SmellDetectors
-            |
-            |
-            |
-    Generate the AST out of the given source using SourceCode#syntax_tree, which works like this:
-
-      - We generate a "rough" AST using the "parser" gem
-      - We then obtain the comments from the source code separately
-      - We pass this unprocessed AST and the comment_map to TreeDresser#dress which
-        returns an instance of Reek::AST::SexpNode with type-dependent SexpExtensions mixed in.
-
-    An example should make this more palpable.
-    Given:
-
-      class C
-        def m
-          puts 'nada'
-        end
-      end
-
-    The AST generated by the parser gem (consisting of Parser::AST::Node) looks like this:
-
-       (class
-         (const nil :C)
-          nil
-         (def :m
-           (args)
-           (send nil :puts
-             (str "nada"))))
-
-    TreeDresser#dress would transform this into a very similar tree, but this time not consisting
-    of Parser::AST::Node but of Reek::AST::SexpNode and with node-dependent SexpExtensions
-    mixed in (noted in []):
-
-       (class                 [AST::SexpExtensions::ClassNode, AST::SexpExtensions::ModuleNode]
-         (const nil :C)       [AST::SexpExtensions::ConstNode]
-          nil
-         (def :m              [AST::SexpExtensions::DefNode, AST::SexpExtensions::MethodNodeBase]
-           (args)             [AST::SexpExtensions::ArgsNode]
-           (send nil :puts    [AST::SexpExtensions::SendNode]
-             (str "nada"))))
-            |
-            |
-            |
-      A ContextBuilder then traverses this now adorned tree again and
-      runs all SmellDetectors from the DetectorRepository above

data/docs/Instance-Variable-Assumption.md

@@ -1,163 +0,0 @@
-# Instance Variable Assumption
-
-## Introduction
-
-Classes should not assume that instance variables are set or present outside of the current class definition.
-
-Good:
-
-```Ruby
-class Foo
-  def initialize
-    @bar = :foo
-  end
-
-  def foo?
-    @bar == :foo
-  end
-end
-```
-
-Good as well:
-
-```Ruby
-class Foo
-  def foo?
-    bar == :foo
-  end
-
-  def bar
-    @bar ||= :foo
-  end
-end
-```
-
-Bad:
-
-```Ruby
-class Foo
-  def go_foo!
-    @bar = :foo
-  end
-
-  def foo?
-    @bar == :foo
-  end
-end
-```
-
-## Example
-
-Running Reek on:
-
-```Ruby
-class Dummy
-  def test
-    @ivar
-  end
-end
-```
-
-would report:
-
-```Bash
-  [1]:InstanceVariableAssumption: Dummy assumes too much for instance variable @ivar
-```
-
-Note that this example would trigger this smell warning as well:
-
-```Ruby
-class Parent
-  def initialize(omg)
-    @omg = omg
-  end
-end
-
-class Child < Parent
-  def foo
-    @omg
-  end
-end
-```
-
-The way to address the smell warning is that you should create an `attr_reader` to use `@omg` in the subclass and not access `@omg` directly like this:
-
-```Ruby
-class Parent
-  attr_reader :omg
-
-  def initialize(omg)
-    @omg = omg
-  end
-end
-
-class Child < Parent
-  def foo
-    omg
-  end
-end
-```
-
-Directly accessing instance variables is considered a smell because it [breaks encapsulation](http://designisrefactoring.com/2015/03/29/organizing-data-self-encapsulation/) and makes it harder to reason about code.
-
-If you don't want to expose those methods as public API just make them private like this:
-
-```Ruby
-class Parent
-  def initialize(omg)
-    @omg = omg
-  end
-
-  private
-  attr_reader :omg
-end
-
-class Child < Parent
-  def foo
-    omg
-  end
-end
-```
-
-
-## Current Support in Reek
-
-An instance variable must:
-
-* be set in the constructor
-* or be accessed through a method with lazy initialization / memoization.
-
-If not, _Instance Variable Assumption_ will be reported.
-
-## Using Instance Variable Assumption in a Rails context
-
-In ActiveRecord it seems common to use callbacks like `after_initialize` to initialize instance variables as
-outlined [here](https://stackoverflow.com/questions/41165520/overriding-applicationrecord-initialize-bad-idea)
-or [here](http://blog.dalethatcher.com/2008/03/rails-dont-override-initialize-on.html)
-instead of overriding the `initialize` method.
-If an instance variable is initialized in such a callback Reek will report it correspondingly.
-
-This would smell for instance:
-
-```Ruby
-class Sample < ApplicationRecord
-  after_initialize do
-    @my_var = false
-  end
-end
-```
-
-Since Reek cannot reliably detect that is used in a Rails context we recommend to disable this detector
-for "app/models" like this:
-
-```Yaml
-directories:
-  # Your other configuration....
-  "app/models":
-    InstanceVariableAssumption:
-      enabled: false
-```
-
-## Configuration
-
-_Instance Variable Assumption_ supports the [Basic Smell Options](Basic-Smell-Options.md).