reek 4.5.1 → 5.0.0

data/README.md

@@ -7,7 +7,7 @@
 - [Overview](#overview)
 - [Quickstart](#quickstart)
 - [Example](#example)
-- [Supported rubies](#supported-rubies)
+- [Supported Ruby versions](#supported-ruby-versions)
 - [Fixing Smell Warnings](#fixing-smell-warnings)
 - [Sources](#sources)
 - [Code smells](#code-smells)
@@ -16,8 +16,9 @@
   - [Configuration file](#configuration-file)
     - [Configuration loading](#configuration-loading)
     - [Configuration options](#configuration-options)
-  - [Source code comments](#source-code-comments)
   - [Generating a 'todo' list](#generating-a-todo-list)
+  - [Beware of multiple configuration files](#beware-of-multiple-configuration-files)
+  - [Source code comments](#source-code-comments)
 - [Usage](#usage)
 - [Developing Reek / Contributing](#developing-reek--contributing)
 - [Output formats](#output-formats)
@@ -38,13 +39,18 @@
 * [![Gem Version](https://badge.fury.io/rb/reek.svg)](https://badge.fury.io/rb/reek)
 * ![](http://img.shields.io/github/tag/troessner/reek.svg)
 * ![](http://img.shields.io/badge/license-MIT-brightgreen.svg)
-* [![Dependency Status](https://gemnasium.com/badges/github.com/troessner/reek.svg)](https://gemnasium.com/github.com/troessner/reek)
 * [![Inline docs](https://inch-ci.org/github/troessner/reek.png)](https://inch-ci.org/github/troessner/reek)
 * [![Code Climate](https://codeclimate.com/github/troessner/reek/badges/gpa.svg)](https://codeclimate.com/github/troessner/reek)
 * [![codebeat](https://codebeat.co/badges/42fed4ff-3e55-4aed-8ecc-409b4aa539b3)](https://codebeat.co/projects/github-com-troessner-reek)
 * ![](http://ruby-gem-downloads-badge.herokuapp.com/reek?type=total)
 * ![](http://ruby-gem-downloads-badge.herokuapp.com/reek?label=downloads-current-version)
 
+## Reek 5 is out!
+
+Reek 5 is out and with it a bunch of breaking changes. If you're a new user you can just
+continue with the quickstart below. If you're a Reek 4 user and would like to upgrade to 5, don't
+worry, this shouldn't take you more than 10 minutes. Check out our [Upgrade Guide](docs/Reek-4-to-Reek-5-migration.md).
+
 ## Quickstart
 
 Reek is a tool that examines Ruby classes, modules and methods and reports any
@@ -52,7 +58,7 @@ Reek is a tool that examines Ruby classes, modules and methods and reports any
 
 For an excellent introduction to
 [Code Smells](docs/Code-Smells.md) and Reek check out [this blog post](https://blog.codeship.com/how-to-find-ruby-code-smells-with-reek/)
-or [that one](https://troessner.svbtle.com/the-latest-and-greatest-additions-to-reek). There is also [this talk](https://www.youtube.com/watch?v=ZzqOuHI5MkA) from the [RubyConf Portugal](http://rubyconf.pt/).
+or [that one](https://troessner.svbtle.com/the-latest-and-greatest-additions-to-reek). There is also [this talk](https://www.youtube.com/watch?v=pazYe7WRWRU) from [RubyConfBY](http://rubyconference.by/) (there is also a [slide deck](http://talks.chastell.net/rubyconf-by-lt-2016/) if you prefer that).
 
 Install it via rubygems:
 
@@ -83,24 +89,24 @@ end
 Reek will report the following code smells in this file:
 
 ```
-$ reek demo.rb
+$ reek --no-documentation demo.rb
 Inspecting 1 file(s):
 S
 
 demo.rb -- 2 warnings:
-  [4]:UncommunicativeMethodName: Smelly#x has the name 'x' [https://github.com/troessner/reek/blob/master/docs/Uncommunicative-Method-Name.md]
-  [5]:UncommunicativeVariableName: Smelly#x has the variable name 'y' [https://github.com/troessner/reek/blob/master/docs/Uncommunicative-Variable-Name.md]
+  [4]:UncommunicativeMethodName: Smelly#x has the name 'x'
+  [5]:UncommunicativeVariableName: Smelly#x has the variable name 'y'
 ```
 
-## Supported rubies
+## Supported Ruby versions
 
-Reek is officially running on the following MRI rubies:
+Reek is officially supported for the following CRuby versions:
 
-  - 2.1
-  - 2.2
   - 2.3
+  - 2.4
+  - 2.5
 
-Other rubies like Rubinius or JRuby are not officially supported but should work as well.
+Other Ruby implementations (like Rubinius or JRuby) are not officially supported but should work as well.
 
 ## Fixing Smell Warnings
 
@@ -251,12 +257,13 @@ For a summary of those CLI options see [Command-Line Options](docs/Command-Line-
 #### Configuration loading
 
 Configuring Reek via a configuration file is by far the most powerful way.
+Reek expects this filename to be `.reek.yml` but you can override this via the CLI `-c` switch (see below).
 
-There are three ways of passing Reek a configuration file:
+There are three ways of passing Reek the configuration file:
 
 1. Using the CLI `-c` switch (see [_Command-line interface_](#command-line-interface) above)
-2. Having a file ending with `.reek` either in your current working directory or in a parent directory (more on that later)
-3. Having a file ending with `.reek` in your home directory
+2. Having the configuration file either in your current working directory or in a parent directory (more on that later)
+3. Having the configuration file in your home directory
 
 The order in which Reek tries to find such a configuration
 file is exactly the above: first it checks if we have given
@@ -274,43 +281,46 @@ of how many `*.reek` files you might have on your filesystem.
 
 We put a lot of effort into making Reek's configuration as self explanatory as possible so the
 best way to understand it is by looking at a simple
-example (e.g. `config.reek` in your project directory):
+example (e.g. `.reek.yml` in your project directory):
 
 ```yaml
 ---
 
 ### Generic smell configuration
 
-# You can disable smells completely
-IrresponsibleModule:
-  enabled: false
-
-# You can use filters to silence Reek warnings.
-# Either because you simply disagree with Reek (we are not the police) or
-# because you want to fix this at a later point in time.
-NestedIterators:
-  exclude:
-    - "MyWorker#self.class_method" # should be refactored
-    - "AnotherWorker#instance_method" # should be refactored as well
-
-# A lot of smells allow fine tuning their configuration. You can look up all available options
-# in the corresponding smell documentation in /docs. In most cases you probably can just go
-# with the defaults as documented in defaults.reek.
-DataClump:
-  max_copies: 3
-  min_clump_size: 3
+detectors:
+  # You can disable smells completely
+  IrresponsibleModule:
+    enabled: false
+  
+  # You can use filters to silence Reek warnings.
+  # Either because you simply disagree with Reek (we are not the police) or
+  # because you want to fix this at a later point in time.
+  NestedIterators:
+    exclude:
+      - "MyWorker#self.class_method" # should be refactored
+      - "AnotherWorker#instance_method" # should be refactored as well
+  
+  # A lot of smells allow fine tuning their configuration. You can look up all available options
+  # in the corresponding smell documentation in /docs. In most cases you probably can just go
+  # with the defaults as documented in defaults.reek.yml.
+  DataClump:
+    max_copies: 3
+    min_clump_size: 3
 
 ### Directory specific configuration
 
 # You can configure smells on a per-directory base.
 # E.g. the classic Rails case: controllers smell of NestedIterators (see /docs/Nested-Iterators.md) and
 # helpers smell of UtilityFunction (see docs/Utility-Function.md)
-"web_app/app/controllers":
-  NestedIterators:
-    enabled: false
-"web_app/app/helpers":
-  UtilityFunction:
-    enabled: false
+# Note that we only allow configuration on a directory level, not a file level, so all paths have to point to directories.
+directories:
+  "web_app/app/controllers":
+    NestedIterators:
+      enabled: false
+  "web_app/app/helpers":
+    UtilityFunction:
+      enabled: false
 
 ### Excluding directories
 
@@ -320,6 +330,14 @@ exclude_paths:
   - lib/rake/legacy_tasks
 ```
 
+As you see above, Reek's configuration consists of 3 different sections denoted by 3 different keys:
+
+* detectors
+* directories
+* exclude_paths
+
+Whatever you add to your configuration should be scoped under one of those keys.
+
 If you have a directory directive for which a default directive exists, the more specific
 one (which is the directory directive) will take precedence.
 
@@ -327,15 +345,12 @@ This configuration for instance:
 
 ```yaml
 ---
-IrresponsibleModule:
-  enabled: false
-
-TooManyStatements:
-  max_statements: 5
-
-"app/controllers":
+detectors:
+  IrresponsibleModule:
+    enabled: false
+  
   TooManyStatements:
-    max_statements: 10
+    max_statements: 5
 ```
 
 translates to:
@@ -344,16 +359,29 @@ translates to:
 * TooManyStatements#max_statements is 10 in "app/controllers"
 * TooManyStatements#max_statements is 5 everywhere else
 
-For more details please check out the [Basic Smell Options](docs/Basic-Smell-Options.md)
-which are supported by every smell type. As you can see above, certain smell
-types offer a configuration that goes beyond that of the basic smell options, for instance
+Every smell detector supports our [Basic Smell Options](docs/Basic-Smell-Options.md). As you can see above,
+certain smell types offer a configuration that goes beyond that of the basic smell options, for instance
 [Data Clump](docs/Data-Clump.md).
 All options that go beyond the [Basic Smell Options](docs/Basic-Smell-Options.md)
 are documented in the corresponding smell type /docs page (if you want to get a quick overview over all possible
-configurations you can also check out [the `default.reek` file in this repository](defaults.reek).
+configurations you can also check out [the `defaults.reek.yml` file in this repository](docs/defaults.reek.yml).
 
 Note that you do not need a configuration file at all.
-If you're fine with all the [defaults](defaults.reek) we set you can skip this completely.
+If you're fine with all the [defaults.reek.yml](docs/defaults.reek.yml) we set you can skip this completely.
+
+Don't worry about introducing a mistake in your configuration file that might go unnoticed - Reek uses a
+schema to validate your configuration against on start up and will faily loudly in case you
+misspelled an option or used the wrong data type for a value like this:
+
+```
+Error: We found some problems with your configuration file: [/detectors/DetectorWithTypo] key 'DetectorWithTypo:' is undefined.
+```
+
+Reek takes one configuration file and one configuration file only with `.reek.yml` being the default name.
+
+In case you have to have one or more configuration files in the directory (e.g. you're
+toying around with different, mutually exclusive settings) you need to tell Reek
+explicitly which file to use via `reek -c config.reek`.
 
 ### Source code comments
 
@@ -377,7 +405,7 @@ def smelly_method foo
 end
 ```
 
-This is an incredible powerful feature and further explained under [Smell Suppresion](docs/Smell-Suppression.md).
+This is an incredibly powerful feature and further explained under [Smell Suppresion](docs/Smell-Suppression.md).
 
 ### Generating a 'todo' list
 
@@ -470,7 +498,9 @@ You can also run:
 bundle exec rake ci
 ```
 
-This will run everything the default task runs and also [Ataru](https://github.com/CodePadawans/ataru) and [Mutant](https://github.com/mbj/mutant). This is the task that we run on Travis as well and that determines if your pull request is green or red.
+This will run everything the default task runs and also
+[Ataru](https://github.com/CodePadawans/ataru). This is the task that we run on
+Travis as well and that determines if your pull request is green or red.
 
 Another useful Rake task is the `console` task. This will throw you right into an environment where you can play around with Reeks modules and classes:
 
@@ -512,6 +542,20 @@ If you don't feel like getting your hands dirty with code there are still other
 * Open up an [issue](https://github.com/troessner/reek/issues) and report bugs
 * Suggest other improvements like additional smells for instance
 
+### Running Code Climate locally
+
+If you run into Code Climate issues (e.g., go over code duplication
+threshold) you might want to be able to run Code Climate against
+the Reek codebase locally. To do this, you need to do the following:
+
+* [install Docker CE](https://docs.docker.com/engine/installation/)
+* [install Code Climate CLI](https://github.com/codeclimate/codeclimate#installation)
+* `gem install codeclimate`
+* `codeclimate engines:install`
+
+Now you can run various Code Climate engines,
+e.g., `codeclimate analyze -e duplication`
+
 ## Output formats
 
 Reek supports 5 output formats:
@@ -528,20 +572,24 @@ Making Reek "Rails"-friendly is fairly simple since we support directory specifi
 Just add this to your configuration file:
 
 ```Yaml
-"app/controllers":
-  IrresponsibleModule:
-    enabled: false
-  NestedIterators:
-    max_allowed_nesting: 2
-  UnusedPrivateMethod:
-    enabled: false
-  InstanceVariableAssumption:
-    enabled: false
-"app/helpers":
-  IrresponsibleModule:
-    enabled: false
-  UtilityFunction:
-    enabled: false
+directories:
+  "app/controllers":
+    IrresponsibleModule:
+      enabled: false
+    NestedIterators:
+      max_allowed_nesting: 2
+    UnusedPrivateMethod:
+      enabled: false
+    InstanceVariableAssumption:
+      enabled: false
+  "app/helpers":
+    IrresponsibleModule:
+      enabled: false
+    UtilityFunction:
+      enabled: false
+  "app/mailers":
+    InstanceVariableAssumption:
+      enabled: false
 ```
 
 Be careful though, Reek does not merge your configuration entries, so if you already have a directory directive for "app/controllers" or "app/helpers" you need to update those directives instead of copying the above YAML sample into your configuration file.
@@ -554,6 +602,7 @@ Be careful though, Reek does not merge your configuration entries, so if you alr
 * [TextMate Bundle](https://github.com/peeyush1234/reek.tmbundle)
 * [Atom plugin](https://atom.io/packages/linter-reek)
 * [SublimeLinter plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-reek)
+* [VS Code plugin](https://github.com/rubyide/vscode-ruby)
 * [Emacs plugin](https://github.com/hanmoi-choi/reek-emacs)
 
 ### Projects that use or support us

data/Rakefile

@@ -3,6 +3,19 @@ require 'rake/clean'
 
 Dir['tasks/**/*.rake'].each { |t| load t }
 
-task local_test_run: [:test, :rubocop, 'test:quality']
-task ci: [:test, :rubocop, 'test:quality', :ataru]
-task default: :local_test_run
+task :ci do
+  [
+    'test:spec',
+    'configuration:update_default_configuration',
+    'test:features',
+    :rubocop,
+    'test:quality',
+    :ataru
+  ].each do |name|
+    puts "\n=== Running #{name}...\n"
+    Rake::Task[name].invoke
+    puts "\n=== Running #{name} -> Done\n"
+  end
+end
+
+task default: :ci

data/bin/code_climate_reek

@@ -1,5 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
+
 #
 # Wrapper for the CodeClimate integration.
 

data/bin/reek

@@ -1,10 +1,9 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
+
 #
 # Reek examines Ruby source code for smells.
-# Visit https://wiki.github.com/troessner/reek for docs etc.
-#
-# Author: Kevin Rutherford
+# Visit https://github.com/troessner/reek for docs etc.
 #
 
 require_relative '../lib/reek'

data/docs/API.md

@@ -89,7 +89,7 @@ XMLReport
 
 ## Configuration
 
-Given you have the following configuration file called `config.reek` in your root directory:
+Given you have the following configuration file called `.reek.yml` in your root directory:
 
 ```Yaml
 ---
@@ -106,7 +106,7 @@ You can now use either
 Reek::Configuration::AppConfiguration.from_path Pathname.new('config.reek')
 ```
 
-but you can also pass a hash with the contents of the `config.reek` YAML file
+but you can also pass a hash with the contents of the `.reek.yml` YAML file
 to `Reek::Configuration::AppConfiguration.from_hash`.
 
 Given the example above you would load that as follows:
@@ -140,13 +140,6 @@ string -- 2 warnings:
   Dirty#call_me has the parameter name 'b' (UncommunicativeParameterName)
 ```
 
-Instead of the smell detector names you can also use the full detector class in
-your configuration hash, for example:
-
-```ruby
-config_hash = { Reek::SmellDetectors::IrresponsibleModule => { 'enabled' => false } }
-```
-
 Of course, directory specific configuration and excluded paths are supported as
 well:
 

data/docs/Basic-Smell-Options.md

@@ -7,14 +7,14 @@ Every smell detector in Reek offers at least the following configuration options
 | Option         | Value       | Effect  |
 | ---------------|-------------|---------|
 | `enabled` |  Boolean | Determines whether the smell detector is active. Defaults to `true` |
-| `exclude` | an array of strings or regular expressions | Ignores any context whose full description (see <strong>%c</strong> in [Command-Line Options](Command-Line-Options.md)) matches any element of this array. |
+| `exclude` | an array of strings that will be converted into regular expressions | Ignores any context whose full description matches any element of this array. |
 
-The file `defaults.reek` (shipped with the Reek gem) lists any default
+The file `docs/defaults.reek.yml` (shipped with the Reek gem) lists any default
 exclusions for each smell.
 
 ## Examples
 
-<u>An easy one:</u>
+**An easy one:**
 
 To stop Reek reporting smells in any method called `write` you might create a configuration file containing this:
 
@@ -24,15 +24,9 @@ DuplicateMethodCall:
   - write
 ```
 
-Or a little more sophisticated using a Ruby regex like this:
+Internally Reek will convert this to the Regexp /write/.
 
-```yaml
-DuplicateMethodCall:
-  exclude:
-  - !ruby/regexp /write/
-```
-
-<u>A more sophisticated one:</u>
+**A more sophisticated one:**
 
 ```yaml
 FeatureEnvy:
@@ -43,3 +37,49 @@ FeatureEnvy:
 ```
 
 This would not report FeatureEnvy for the instance method `MyModel#do_things`, the whole module `MyHelper` and the `respond` instance method of `ApplicationController`
+
+## Advanced configuration
+
+Sometimes just strings are not enough for configuration. E.g. consider this code sample:
+
+```Ruby
+class Klass
+  def foo1; end
+  def foo1bar; end
+end
+```
+Both "Klass#foo1" and "Klass#foo1bar" will smell of UncommunicativeMethodName. Now let's assume
+you are ok with "Klass#foo1" but not "Klass#foo1bar".
+Just having this configuration 
+
+```yaml
+UncommunicativeMethodName:
+  exclude:
+    - "Klass#foo1"
+```
+
+wouldn't work because now "Klass#foo1bar" wouldn't smell as well.
+
+For this reason Reek has a special syntax that allows you to use regexes by using a forward slash at the beginning and the end of the string.
+Everything within the forward slashes will be loaded as a regex.
+
+A possible configuration that hat excludes "Klass#foo1" from this scan but not "Klass#foo1bar" could look like this:
+
+```yaml
+UncommunicativeMethodName:
+  exclude:
+    - "/Klass#foo1$/"
+```
+
+## Reek 4
+
+In Reek 4 you could also pass regexes to `exclude`, meaning this was perfectly valid as well:
+
+```yaml
+DuplicateMethodCall:
+  exclude:
+    - !ruby/regexp /write/
+```
+
+Support for this has been scrapped with Reek 5 to make the Reek configuration more yaml standard compliant.
+You can still pass in regexes, you just have to wrap them into a string. Please see "Advanced configuration" above.

data/docs/Code-Smells.md

@@ -23,7 +23,7 @@ Reek currently includes checks for the following smells:
   * [Utility Function](Utility-Function.md)
 * [Module Initialize](Module-Initialize.md)
 * [Nested Iterators](Nested-Iterators.md)
-* [Prima-Donna-Method](Prima-Donna-Method.md)
+* [Missing Safe Method](Missing-Safe-Method.md), formerly known as Prima Donna Method
 * [Simulated Polymorphism](Simulated-Polymorphism.md), including
   * [Manual Dispatch](Manual-Dispatch.md)
   * [Nil Check](Nil-Check.md)

data/docs/Command-Line-Options.md

@@ -12,6 +12,16 @@ reek -h
 
 for details.
 
+## Telling Reek to use a specific configuration file
+
+In case your configuration file is not in the standard location (that would be your project directory or
+whatever directory you're running Reek from) you can specify a configuration file with the `-c` option
+like this:
+
+```Bash
+reek -c /somewhere/on/your/filesystem/reek_config.yml lib/
+```
+
 ## Telling Reek Which Code to Check
 
 Probably the most standard use case would be to check all Ruby files in the lib directory:
@@ -91,10 +101,10 @@ mess.rb -- 2 warnings:
   [2]:x has the name 'x' (UncommunicativeMethodName)
 ```
 
-### Enable the ultra-verbose mode
+### Enable the verbose mode
 
-_reek_ has a ultra-verbose mode which you might find helpful as a beginner. "ultra-verbose" just means that behind each warning a helpful link will be displayed which leads directly to the corresponding _reek_ wiki page.
-This mode can be enabled via the "-U" or "--ultra-verbose" flag.
+_reek_ has a verbose mode which you might find helpful as a beginner. "verbose" just means that behind each warning a helpful link will be displayed which leads directly to the corresponding _reek_ documentation page.
+This mode can be enabled via the "-U" or "--documentation" flag.
 
 So for instance, if your test file would smell of _ClassVariable_, this is what the _reek_ output would look like:
 
@@ -103,7 +113,7 @@ reek -U test.rb
 ```
 ```
 test.rb -- 1 warning:
-  [2]:Dummy declares the class variable @@class_variable (ClassVariable) [https://github.com/troessner/reek/wiki/Class-Variable]
+  [2]:Dummy declares the class variable @@class_variable (ClassVariable) [https://github.com/troessner/reek/blob/master/docs/Class-Variable.md]
 ```
 
 Note the link at the end.

data/docs/Duplicate-Method-Call.md

@@ -42,7 +42,55 @@ The approach you take will depend on balancing other factors in your code.
 
 ## Current support in Reek
 
-Reek's Duplicate Method Call detector checks for repeated identical method calls within any one method definition. This is intended to complement the checks performed by tools such as [Flay](http://ruby.sadi.st/Flay.html) and [Simian](http://www.redhillconsulting.com.au/products/simian/).
+Reek's Duplicate Method Call detector checks for repeated identical method calls within
+any one method definition. This is intended to complement the checks performed by tools
+such as [Flay](http://ruby.sadi.st/Flay.html) and [Simian](http://www.redhillconsulting.com.au/products/simian/).
+
+## Edge cases
+
+Be aware that there are some edge cases like this code:
+
+```Ruby
+class Foo
+  def bar(switch)
+    case switch
+    when :a
+      ->(arg) { arg.call_me(:maybe); do_something }
+    when :b
+      ->(arg) { arg.call_me(:maybe); do_something_else }
+    when :c
+      ->(arg) { arg.call_me(:maybe); do_something_different }
+    end
+  end
+end
+```
+
+Reek cannot reliably detect that each call's receiver is a different arg and will report:
+
+```
+[5, 7, 9]:DuplicateMethodCall: Foo#bar calls 'arg.call_me(:maybe)' 3 times
+```
+  
+If you're running into this problem you can disable this smell detector for this method either via
+configuration:
+
+```Yaml
+---
+DuplicateMethodCall:
+  exclude:
+    - 'Foo#bar'
+```
+
+or via source code comment:
+
+```Ruby
+class Foo
+  # :reek:DuplicateMethodCall
+  def bar(switch)
+    # ....
+  end
+end
+```
 
 ## Configuration
 

data/docs/Feature-Envy.md

@@ -40,6 +40,50 @@ belongs to the Item class, not the Warehouse.
 
 _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.