reek 4.7.3 → 5.0.0

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.

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

@@ -41,7 +41,6 @@ module Reek
           # "smell_warning" is defined in BaseDetector and should be used by you
           # to construct smell warnings
           smell_warning(
-            context: context,
             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
@@ -62,7 +61,7 @@ end
 
 For your detector to be properly loaded you need to require it in `lib/reek/smell_detectors.rb` as well.
 
-### defaults.reek
+### defaults.reek.yml
 
 After you ran
 
@@ -70,7 +69,7 @@ After you ran
 bundle exec rake
 ```
 
-for the first time with your shiny new detector in place the `defaults.reek`
+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.
 

data/docs/Instance-Variable-Assumption.md

@@ -61,7 +61,7 @@ end
 would report:
 
 ```Bash
-  [1]:InstanceVariableAssumption: Dummy assumes too much for instance variable @ivar [https://github.com/troessner/reek/blob/master/docs/Instance-Variable-Assumption.md]
+  [1]:InstanceVariableAssumption: Dummy assumes too much for instance variable @ivar
 ```
 
 Note that this example would trigger this smell warning as well:

data/docs/{Prima-Donna-Method.md → Missing-Safe-Method.md}

@@ -1,8 +1,8 @@
-# Prima Donna Method
+# Missing Safe Method
 
 ## Introduction
 
-Candidate methods for the _Prima Donna Method_ smell are methods whose names
+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
@@ -13,14 +13,16 @@ An exclamation mark in method names means (the explanation below is taken from
 > 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 _Prima Donna Method_ if and only if her non-bang
+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
@@ -33,7 +35,7 @@ class C
 end
 ```
 
-Reek would report the _Prima Donna Method_ smell for `bar!`, but not for `foo!`.
+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:
 
@@ -55,12 +57,12 @@ class Daughter < Parent
 end
 ```
 
-In this example, Reek would not report the _Prima Donna Method_ smell for the
+In this example, Reek would not report the _Missing Safe Method_ smell for the
 method `foo` of the `Dangerous` module.
 
 ## Configuration
 
-_Prima Donna Method_ offers the [Basic Smell Options](Basic-Smell-Options.md).
+_Missing Safe Method_ offers the [Basic Smell Options](Basic-Smell-Options.md).
 
 ## Example configuration via source comment
 
@@ -77,12 +79,12 @@ This would report:
 
 >>
 ruby.rb -- 1 warning:
-  [1]:PrimaDonnaMethod: Alfa has prima donna method 'bravo!'
+  [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:PrimaDonnaMethod { exclude: [ bravo! ] }
+# :reek:MissingSafeMethod { exclude: [ bravo! ] }
 class Alfa
   def bravo!
   end

data/docs/Rake-Task.md

@@ -33,7 +33,7 @@ An more sophisticated rake task that would make use of all available configurati
 ```Ruby
 Reek::Rake::Task.new do |t|
   t.name          = 'custom_rake' # Whatever name you want. Defaults to "reek".
-  t.config_file   = 'config/config.reek' # Defaults to nothing.
+  t.config_file   = 'config/.reek.yml' # Defaults to nothing.
   t.source_files  = 'vendor/**/*.rb' # Glob pattern to match source files. Defaults to lib/**/*.rb
   t.reek_opts     = '-U'  # Defaults to ''. You can pass all the options here in that are shown by "reek -h"
   t.fail_on_error = false # Defaults to true

data/docs/Reek-4-to-Reek-5-migration.md

@@ -0,0 +1,193 @@
+## Reek 4 to Reek 5 migration
+
+### Schema validation
+
+Reek now 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.
+```
+
+Obviously this might affect existing configuration files that until now contained an error nobody noticed.
+
+### Scoping detectors under `detectors`
+
+In Reek 4 you could just configure your detectors on top level like this:
+
+```yaml
+UncommunicativeMethodName:
+  accept:
+    - foobar
+UnusedPrivateMethod:
+  exclude:
+    - app/controllers  
+```
+
+In Reek 5 you have to scope your detector configurations under the `detectors` key:
+
+```yaml
+detectors:
+  UncommunicativeMethodName:
+    accept:
+      - foobar
+  UnusedPrivateMethod:
+    exclude:
+    - app/controllers  
+```
+
+### Move directory directives under a special key
+
+In Reek 4 you could apply directory specific directives like this:
+
+```Yaml
+---
+"web_app/app/controllers":
+  NestedIterators:
+    enabled: false
+"web_app/app/helpers":
+  UtilityFunction:
+    enabled: false
+```
+
+which was nice and easy but also quite messy. With Reek 5 you'll have to scope this under a `directories`
+key like this:
+
+```Yaml
+---
+directories:
+  "web_app/app/controllers":
+    NestedIterators:
+      enabled: false
+  "web_app/app/helpers":
+    UtilityFunction:
+      enabled: false
+```
+
+### No more regular expressions in Reeks configuration
+
+In Reek 4 you could pass regular expressions to the `accept` or `reject` settings of
+ 
+* [Uncommunicative Method Name](Uncommunicative-Method-Name.md)
+* [Uncommunicative Module Name](Uncommunicative-Module-Name.md)
+* [Uncommunicative Parameter Name](Uncommunicative-Parameter-Name.md)
+* [Uncommunicative Variable Name](Uncommunicative-Variable-Name.md)
+
+and to the `exclude` settings which are part of our [Basic Smell Options](docs/Basic-Smell-Options.md).
+ 
+This means that this configuration was perfectly valid:
+
+```yaml
+detectors:
+  UncommunicativeMethodName:
+    accept:
+      - !ruby/regexp /foobar/
+  UnusedPrivateMethod:
+    exclude:
+      - !ruby/regexp /i am(.*)unused/  
+```
+
+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 using a forward slash at the
+beginning and at the end of the string like this:
+
+```Yaml
+---
+UncommunicativeMethodName:
+  accept:
+    - "/^foobar$/"
+UnusedPrivateMethod:
+  exclude:
+    - "/i am(.*)unused/"  
+```
+
+Everything within the forward slashes will be loaded as a regex.
+
+### No more single item shortcuts for list items 
+
+You cant use a configuration option that is supposed to be a list with a single element like this anymore:
+
+```Yaml
+---
+UncommunicativeMethodName:
+  accept: foobar
+UnusedPrivateMethod:
+  exclude: omg  
+```
+
+You'll have to use a proper list here like this:
+
+```Yaml
+---
+UncommunicativeMethodName:
+  accept: 
+    - foobar
+UnusedPrivateMethod:
+  exclude:
+    - omg  
+```
+
+## Failing on syntax errors in source files
+
+Previously Reek would just continue on syntax errors in source files which might have been convenient but
+not necessarily fitting for a tool that's all about code quality. With Reek 5, Reek will fail hard on
+invalid source files.
+
+### API changes
+
+This is something that will only affect very advanced users. In case you have no idea what this might be about
+you can just skip it or check out our [Developer API](docs/API.md).
+
+#### Allow only detector names in configuration hash
+
+In Reek 4 you could build your configuration like this:
+
+```ruby
+config_hash = { Reek::SmellDetectors::IrresponsibleModule => { 'enabled' => false } }
+```
+
+or like this:
+
+```ruby
+config_hash = { 'IrresponsibleModule' => { 'enabled' => false } }
+```
+
+Starting with Reek 5, the first way is not working anymore and the latter one is what you'll have to use.
+
+#### Do not accept a class as parameter for reek_of
+
+In the same vein as the change above you also can't use fully qualified detector names like this:
+
+```Ruby
+ reek_of(Reek::SmellDetectors::DuplicateMethodCall)
+ ```
+ 
+The only supported way now is either as symbol or string:
+ 
+```Ruby
+reek_of(:DuplicateMethodCall)
+reek_of('DuplicateMethodCall')
+```
+
+## Smaller changes
+
+* `PrimaDonnaMethod` has been given the better name `MissingSafeMethod`
+* `wiki-links` flag has been renamed to `documentation` flag
+* Reek assumes the default configuration file to be named ".reek.yml" and will ignore all other files. You can
+still use any name you want though by passing in a name via the `-c` flag
+* We have dropped the legacy code comment separator ":" at the end of a detector name. If you wanted to configure
+a smell detector via comment before this release you had to use g like this:
+
+```
+# :reek:UnusedPrivateMethod: { exclude: [ bravo ] }
+```
+
+Mind the ":" at the end of "UnusedPrivateMethod". This syntax is disallowed with Reek 5 - you have to drop the ":"
+at the end now like this:
+
+```
+# :reek:UnusedPrivateMethod { exclude: [ bravo ] }
+```
+
+* We have dropped support for Ruby 2.1 and 2.2 since they are officially not supported by the Ruby core team anymore
+

data/docs/Reek-Driven-Development.md

@@ -14,7 +14,7 @@ Reek::Rake::Task.new do |t|
 end
 ```
 
-Now the command `reek` will run Reek on your source code (and in this case, it fails if it finds any smells). For more detailed information about Reek's integration with Rake, see [Rake Task](Rake-Task.md) in this wiki.
+Now the command `reek` will run Reek on your source code (and in this case, it fails if it finds any smells). For more detailed information about Reek's integration with Rake, see [Rake Task](Rake-Task.md).
 
 ## reek/spec
 

data/docs/Uncommunicative-Method-Name.md

@@ -21,8 +21,8 @@ Reek's _Uncommunicative Method Name_ detector supports the
 
 | Option         | Value       | Effect  |
 | ---------------|-------------|---------|
-| `reject` | array of regular expressions or strings | The set of patterns / names that Reek uses to check for bad names. Defaults to `[/^[a-z]$/, /[0-9]$/, /[A-Z]/]`. |
-| `accept` | array of regular expressions or strings | The set of patterns / names that Reek will accept (and not report) even if they match one of the `reject` expressions. |
+| `reject` | array of strings | The set of names that Reek uses to check for bad names. Defaults to single-letter names, names ending with a number or names containing upper case letters. |
+| `accept` | array of strings | The set of names that Reek will accept (and not report) even if they match one of the `reject` expressions. |
 
 An example configuration could look like this:
 
@@ -30,13 +30,15 @@ An example configuration could look like this:
 ---
 UncommunicativeMethodName:
   accept:
-    - !ruby/regexp /x/
+    - x
     - meth1
   reject:
-    - !ruby/regexp /helper/
+    - helper
     - foobar
 ```
 
+Reek will convert whatever you give it as a string to the corresponding regex, so "foobar" from above will be converted to /foobar/ internally. 
+
 Applying a configuration to a source file like this:
 
 ```Ruby
@@ -50,6 +52,43 @@ Reek would report:
 
 ```
 smelly.rb -- 2 warnings:
-  [4]:UncommunicativeMethodName: awesome_helper has the name 'awesome_helper' [https://github.com/troessner/reek/blob/master/docs/Uncommunicative-Method-Name.md]
-  [3]:UncommunicativeMethodName: foobar has the name 'foobar' [https://github.com/troessner/reek/blob/master/docs/Uncommunicative-Method-Name.md]
+  [4]:UncommunicativeMethodName: awesome_helper has the name 'awesome_helper'
+  [3]:UncommunicativeMethodName: foobar has the name 'foobar'
+```
+
+## Advanced configuration
+
+Sometimes just strings are not enough for configuration. E.g. consider this code sample:
+
+```Ruby
+class Klass
+  def foo; end
+  def foobar; end;
+end
 ```
+
+and now imagine that you want to reject the name "foo" but not "foobar". This wouldn't be possible with just using strings.
+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 allows "foobar" but rejects "foo" could look like this:
+
+```Yaml
+---
+UncommunicativeMethodName:
+  reject:
+    - "/^foo$/"
+```
+
+## Reek 4
+
+In Reek 4 you could also pass regexes to `accept` or `reject`, meaning this was perfectly valid as well:
+
+```yaml
+UncommunicativeMethodName:
+  accept:
+    - !ruby/regexp /foobar/
+```
+
+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.