reek 6.0.2 → 6.1.0

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).

data/docs/Irresponsible-Module.md

@@ -1,47 +0,0 @@
-# Irresponsible Module
-
-## Introduction
-
-Classes and modules are the units of reuse and release. It is therefore
-considered good practice to annotate every class and module with a brief
-comment outlining its responsibilities.
-
-For further guideline on how to write good documentation in Ruby, see these
-links:
-- [Rails API documentation guidelines](http://edgeguides.rubyonrails.org/api_documentation_guidelines.html)
-- [Comments tell you why](https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/)
-
-## Example
-
-Given
-
-```Ruby
-class Dummy
-  # Do things...
-end
-```
-
-Reek would emit the following warning:
-
-```
-test.rb -- 1 warning:
-  [1]:IrresponsibleModule: Dummy has no descriptive comment
-```
-
-Fixing this is simple - just an explaining comment:
-
-```Ruby
-# The Dummy class is responsible for ...
-class Dummy
-  # Do things...
-end
-```
-
-## Current Support in Reek
-
-_Irresponsible Module_ checks classes and modules, including those
-created through `Struct.new` and `Class.new` and directly assigned to a constant.
-
-## Configuration
-
-_Irresponsible Module_ supports only the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Large-Class.md

@@ -1,16 +0,0 @@
-# Large Class
-
-## Introduction
-
-A _Large Class_ is a class or module that has a large number of instance
-variables, methods or lines of code in any one piece of its specification.
-(That is, this smell relates to pieces of the class's specification, not to the
-size of the corresponding instance of `Class`.)
-
-## Current Support in Reek
-
-Reek offers three checks in this category.
-
-* [Too Many Constants](Too-Many-Constants.md)
-* [Too Many Instance Variables](Too-Many-Instance-Variables.md)
-* [Too Many Methods](Too-Many-Methods.md)

data/docs/Long-Parameter-List.md

@@ -1,39 +0,0 @@
-# Long Parameter List
-
-## Introduction
-
-A _Long Parameter List_ occurs when a method has a lot of parameters.
-
-## Example
-
-Given
-
-```Ruby
-class Dummy
-  def long_list(foo,bar,baz,fling,flung)
-    puts foo,bar,baz,fling,flung
-  end
-end
-```
-
-Reek would report the following warning:
-
-```
-test.rb -- 1 warning:
-  [2]:Dummy#long_list has 5 parameters (LongParameterList)
-```
-
-A common solution to this problem would be the introduction of parameter objects.
-
-## Current Support in Reek
-
-_Long Parameter List_ reports any method or block with more than 3 parameters.
-
-## Configuration
-
-Reek's _Long Parameter List_ detector supports the
-[Basic Smell Options](Basic-Smell-Options.md), plus:
-
-| Option       | Value   | Effect  |
-| -------------|---------|---------|
-| `max_params` | integer | The maximum number of parameters allowed in a method or block before a warning is issued. Defaults to 3. |

data/docs/Long-Yield-List.md

@@ -1,37 +0,0 @@
-# Long Yield List
-
-## Introduction
-
-A _Long Yield List_ occurs when a method yields a lot of arguments to the block
-it gets passed. It is a special case of [Long Parameter List](Long-Parameter-List.md).
-
-## Example
-
-```Ruby
-class Dummy
-  def yields_a_lot(foo,bar,baz,fling,flung)
-    yield foo,bar,baz,fling,flung
-  end
-end
-```
-
-Reek would report the following warning:
-
-```
-test.rb -- 1 warning:
-  [4]:Dummy#yields_a_lot yields 5 parameters (LongYieldList)
-```
-
-A common solution to this problem would be the introduction of parameter objects.
-
-## Current Support in Reek
-
-Currently _Long Yield List_ reports any method or block with more than 3 parameters.
-
-## Configuration
-
-Reek's _Long Yield List_ detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
-
-| Option       | Value   | Effect  |
-| -------------|---------|---------|
-| `max_params` | integer | The maximum number of parameters allowed in a method or block before a warning is issued. Defaults to 3. |

data/docs/Manual-Dispatch.md

@@ -1,30 +0,0 @@
-## Introduction
-
-Reek reports a _Manual Dispatch_ smell if it finds source code that manually checks whether an object responds to a method before that method is called. Manual dispatch is a type of [Simulated Polymorphism](Simulated-Polymorphism.md) which leads to code that is harder to reason about, debug, and refactor.
-
-## Example
-
-```Ruby
-class MyManualDispatcher
-  attr_reader :foo
-
-  def initialize(foo)
-    @foo = foo
-  end
-
-  def call
-    foo.bar if foo.respond_to?(:bar)
-  end
-end
-```
-
-Reek would emit the following warning:
-
-```
-test.rb -- 1 warning:
-  [9]: MyManualDispatcher manually dispatches method call (ManualDispatch)
-```
-
-## Configuration
-
-_Manual Dispatch_ offers the [Basic Smell Options](Basic-Smell-Options.md).