reek 4.8.1 → 5.6.0

data/README.md

@@ -39,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
@@ -84,26 +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 Ruby versions
 
-Reek is officially supported for the following CRuby versions:
+Reek is officially supported for CRuby 2.3 to 2.6 and for JRuby 9.1 and 9.2.
+Other Ruby implementations (like Rubinius) are not officially supported but
+should work as well.
 
-  - 2.1
-  - 2.2
-  - 2.3
-  - 2.4
-  - 2.5
-
-Other Ruby implementations (like Rubinius or JRuby) are not officially supported but should work as well.
+Note that, on each Ruby version, Reek will use the parser for that version of
+Ruby. So, you should always run Reek using one of your project's target Ruby
+versions.
 
 ## Fixing Smell Warnings
 
@@ -254,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
@@ -277,52 +281,70 @@ 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.
+# A Dir.glob pattern can be used.
+directories:
+  "web_app/app/controllers":
+    NestedIterators:
+      enabled: false
+  "web_app/app/helpers**":
+    UtilityFunction:
+      enabled: false
+  "web_app/lib/**/test/**":
+    UtilityFunction:
+      enabled: false
 
 ### Excluding directories
 
-# Directories below will not be scanned at all
+# Directories and files below will not be scanned at all
 exclude_paths:
   - lib/legacy
   - lib/rake/legacy_tasks
+  - lib/smelly.rb  
 ```
 
+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.
 
@@ -330,15 +352,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:
@@ -347,16 +366,63 @@ 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
+
+In case you need to suppress a smell warning and you can't or don't want to
+use configuration files for whatever reasons you can also use special
+source code comments like this:
+
+```Ruby
+# This method smells of :reek:NestedIterators
+def smelly_method foo
+  foo.each {|bar| bar.each {|baz| baz.qux}}
+end
+```
+
+You can even pass in smell specific configuration settings:
+
+```Ruby
+# :reek:NestedIterators { max_allowed_nesting: 2 }
+def smelly_method foo
+  foo.each {|bar| bar.each {|baz| baz.qux}}
+end
+```
+
+This is an incredibly powerful feature and further explained under [Smell Suppresion](docs/Smell-Suppression.md).
+
+#### Debugging trouble with the configuration
+
+With Reeks dynamic mechanism of finding a configuration file you might run into a situation where you are not
+100% sure what configuration file Reek is using. E.g. you have a project specific configuration file in your
+project root and also another Reek configuration in your HOME directory that you use for all your other projects
+and for whatever reasons Reek seems to be using another configuration file than the one you assumed it would.
+
+In this case you can pass the flag `--show-configuration-path` to Reek which will cause Reek to output the path
+to the configuration file it is using.
 
 ### Generating a 'todo' list
 
@@ -371,29 +437,28 @@ suppress all smell warnings for the current codebase:
 reek --todo lib/
 ```
 
-This will create the file '.todo.reek' in your current working directory.
+This will create the file '.reek.yml' in your current working directory.
 
 You can then use this as your configuration - since your working directory
 probably is your project root in most cases you don't have to tell Reek
-explicitly to use '.todo.reek' because Reek will automatically pick it up
+explicitly to use '.reek.yml' because Reek will automatically pick it up
 and use it as configuration file. See [Configuration Loading](#configuration-loading) above.
 
-If for whatever reasons you decide to put '.todo.reek' somewhere else where
+If for whatever reasons you decide to put '.reek.yml' somewhere else where
 Reek won't pick it up automatically you need to tell Reek explicitly to do so
 via:
 
 ```Bash
-reek -c whatever/.todo.reek lib/
+reek -c whatever/.reek.yml lib/
 ```
 
 It's important to understand that the number one use case of the `--todo` flag
 is to be run once at the beginning of the introduction of Reek to ease the transition.
-If you find yourself re-running Reek with the `--todo` flag in order to silence new warnings
+If you find yourself wanting to re-run Reek with the `--todo` flag in order to silence a lot of new warnings
 you're defeating the purpose of both the `--todo` flag and of Reek itself.
 
-As a consequence, running Reek with the `--todo` flag again will overwrite '.todo.reek' without
-asking (should not be a problem since this file is supposed to be versioned) and
-without taking **any** other configuration file you might have into account.
+As a consequence, running Reek with the `--todo` flag again will not overwrite an existing '.reek.yml'
+and instead abort execution. It also will not take **any** other configuration file you might have into account.
 
 This means that when you run
 
@@ -401,44 +466,10 @@ This means that when you run
 reek -c other_configuration.reek --todo lib/
 ```
 
-`other_configuration.reek` will simply be ignored (as outlined before, Reek
-is supposed to have one configuration file and one file only).
-
-### Beware of multiple configuration files
-
-Reek takes one configuration file and one configuration file only.
-
-If you have more than one configuration file in the same directory Reek
-will not know what configuration file to use. If this happens Reek will
-print a warning on STDERR and exit with the failure exit status 1.
+`other_configuration.reek` will simply be ignored.
 
-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
-
-In case you need to suppress a smell warning and you can't or don't want to
-use configuration files for whatever reasons you can also use special
-source code comments like this:
-
-```Ruby
-# This method smells of :reek:NestedIterators
-def smelly_method foo
-  foo.each {|bar| bar.each {|baz| baz.qux}}
-end
-```
-
-You can even pass in smell specific configuration settings:
-
-```Ruby
-# :reek:NestedIterators { max_allowed_nesting: 2 }
-def smelly_method foo
-  foo.each {|bar| bar.each {|baz| baz.qux}}
-end
-```
-
-This is an incredible powerful feature and further explained under [Smell Suppresion](docs/Smell-Suppression.md).
+Of course you can always just delete the existing .reek.yml file and then run Reek with the `--todo` flag
+but keep in mind that this is not the intended use case of this feature.
 
 ## Usage
 
@@ -479,16 +510,6 @@ bundle exec rake
 
 This will run the tests (RSpec and Cucumber), RuboCop and Reek itself.
 
-You can also run:
-
-```
-bundle exec rake ci
-```
-
-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:
 
 ```
@@ -508,15 +529,6 @@ require 'pry'
 binding.pry
 ```
 
-If you do this, you need to also run the specs with `DEBUG=1` set, e.g.:
-
-```
-DEBUG=1 bundle exec rspec spec/your/file_spec.rb:23
-```
-
-This is necessary because normally all specs run with a timeout of 5 seconds,
-which isn't much if you're busy using Pry.
-
 Have a look at our [Developer API](docs/API.md) for more inspiration.
 
 From then on you should check out:
@@ -559,23 +571,27 @@ 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
-"app/mailers":
-  InstanceVariableAssumption:
-    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
+  "app/models":
+    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.
@@ -588,6 +604,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',
+    'test:performance',
+    'configuration:update_default_configuration',
+    'test:features',
+    :rubocop,
+    'test:quality'
+  ].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/reek

@@ -3,9 +3,7 @@
 
 #
 # 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

@@ -23,13 +23,13 @@ Code says more than a thousand words:
 ```ruby
 require 'reek'
 
-source = <<-EOS
+source = <<-RUBY
   class Dirty
     def m(a,b,c)
       puts a,b
     end
   end
-EOS
+RUBY
 
 reporter = Reek::Report::TextReport.new
 examiner = Reek::Examiner.new source
@@ -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:
@@ -117,13 +117,13 @@ require 'reek'
 config_hash = { 'IrresponsibleModule' => { 'enabled' => false } }
 configuration = Reek::Configuration::AppConfiguration.from_hash config_hash
 
-source = <<-EOS
+source = <<-RUBY
   class Dirty
     def call_me(a,b)
       puts a,b
     end
   end
-EOS
+RUBY
 
 reporter = Reek::Report::TextReport.new
 examiner = Reek::Examiner.new(source, configuration: configuration); nil
@@ -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.