reek 6.0.3 → 6.1.0

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

data/docs/Missing-Safe-Method.md

@@ -1,92 +0,0 @@
-# Missing Safe Method
-
-## Introduction
-
-Candidate methods for the _Missing Safe Method_ smell are methods whose names
-end with an exclamation mark.
-
-An exclamation mark in method names means (the explanation below is taken from
-[here](http://dablog.rubypal.com/2007/8/15/bang-methods-or-danger-will-rubyist)):
-
-> The ! in method names that end with ! means, “This method is dangerous”—or,
-> more precisely, this method is the “dangerous” version of an otherwise
-> equivalent method, with the same name minus the !. “Danger” is relative; the
-> ! doesn’t mean anything at all unless the method name it’s in corresponds to
-> a similar but bang-less method name.
->
-> So, for example, gsub! is the dangerous version of gsub. exit! is the
-> dangerous version of exit. flatten! is the dangerous version of flatten. And
-> so forth.
-
-Such a method is called _Missing Safe Method_ if and only if the non-bang
-version does not exist and this method is reported as a smell.
-
-Missing Safe Method was formerly known as Prima Donna Method. 
-
-## Example
-
-Given
-
-```Ruby
-class C
-  def foo; end
-  def foo!; end
-  def bar!; end
-end
-```
-
-Reek would report the _Missing Safe Method_ smell for `bar!`, but not for `foo!`.
-
-Reek reports this smell only in a class context, not in a module context in order to allow perfectly legit code like this:
-
-
-```Ruby
-class Parent
-  def foo; end
-end
-
-module Dangerous
-  def foo!; end
-end
-
-class Son < Parent
-  include Dangerous
-end
-
-class Daughter < Parent
-end
-```
-
-In this example, Reek would not report the _Missing Safe Method_ smell for the
-method `foo` of the `Dangerous` module.
-
-## Configuration
-
-_Missing Safe Method_ offers the [Basic Smell Options](Basic-Smell-Options.md).
-
-## Example configuration via source comment
-
-Imagine code like this:
-
-```Ruby
-class Alfa
-  def bravo!
-  end
-end
-```
-
-This would report:
-
->>
-ruby.rb -- 1 warning:
-  [1]:MissingSafeMethod: Alfa has missing safe method 'bravo!'
-
-If you want to suppress this warning you can do this via source comment like this:
-
-```Ruby
-# :reek:MissingSafeMethod { exclude: [ bravo! ] }
-class Alfa
-  def bravo!
-  end
-end
-```