reek 3.3.1 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 18055c0f9c08fb0e795cb4417885156291c9f5b7
-  data.tar.gz: b2d41cb4510dd092450c82bae4664bbbb7a10d50
+  metadata.gz: c8492565566dc33ddd04e6474399de644c050c31
+  data.tar.gz: 40d22b046c4c8a9be279dae6aacd3859d7534d46
 SHA512:
-  metadata.gz: 92722d3bdd09267e2c5858414b6f91cf066a6f9c3596033a3845d1c2d7cd768d17eb29e932af6d7ea8a432081f77b6f77092051288903b0377f11f6137c292ff
-  data.tar.gz: 0124c0f5b7d1c4f0f580b545757d1f94d51c2f93310b2dfe922abaa9ef241fc91a4ddadbad07832d6d5e92e99b0d4186b70f194f54f68f995693fbc70afc15e5
+  metadata.gz: e929fb9f9a89fddb7383ed8fd606b22f31977ed43360160a3359cb325b7a56adbd4801ba7ded8993f90aae42f7369cda18be10b1ff2d44ed9181a2711affea84
+  data.tar.gz: ece84cae1ab3d23b457f7f31f6ce47ba48ea65683a82291645803020b418609137fbe5eae6185d1e706ae840a3cbc87a27de4d6abbbef624177cfc13373947e2

data/.rubocop.yml

@@ -18,6 +18,10 @@ Metrics/MethodLength:
 Metrics/LineLength:
   Max: 120
 
+# Keyword arguments make long parameter lists readable
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
 # Indent one level for follow-up lines
 Style/MultilineOperationIndentation:
   EnforcedStyle: indented

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 3.4.0 (2015-09-16)
+
+* (troessner) Make UtilityFunction configurable for non-public methods
+* (troessner) Make FeatureEnvy and UtilityFunction messages more helpful
+* (mvz) Mark public API @public
+
 ## 3.3.1 (2015-09-03)
 
 * (troessner) Fix file list as argument in rake task

data/CONTRIBUTING.md

@@ -51,6 +51,9 @@ Once you’re sure your copy of reek works create your own feature branch from o
 git checkout -b your_feature_or_fix_name
 ```
 
+Make sure you have read our [style guide](docs/style-guide.md) before you
+start contributing.
+
 Then start hacking and add new tests which make sure that your new feature works or
 demonstrate that your fix was needed; please also [write good commit
 messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).

data/README.md

@@ -204,9 +204,9 @@ configurations you can also check out [the `config/default.reek` file in this re
 
 ### Source code comments
 
-`reek` is not the police. 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 source code comments like this:
+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
@@ -215,8 +215,16 @@ def smelly_method foo
 end
 ```
 
-This is further explained under [Smell Suppresion](docs/Smell-Suppression.md).
+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).
 
 ## Usage
 

data/Rakefile

@@ -5,3 +5,4 @@ Dir['tasks/**/*.rake'].each { |t| load t }
 
 task default: :test
 task default: :rubocop unless RUBY_ENGINE == 'rbx'
+task default: 'test:quality'

data/config/defaults.reek

@@ -84,8 +84,7 @@ UncommunicativeModuleName:
   reject:
   - !ruby/regexp /^.$/
   - !ruby/regexp /[0-9]$/
-  accept:
-  - Inline::C
+  accept: []
 UncommunicativeParameterName:
   enabled: true
   exclude: []

data/docs/Nested-Iterators.md

@@ -36,4 +36,9 @@ Nested Iterators reports failing methods only once.
 
 ## Configuration
 
-`Nested Iterators` offers the [Basic Smell Options](Basic-Smell-Options.md).
+`Nested Iterators` offers the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| max_allowed_nesting | integer | The maximum depth of nested iterators. Defaults to 1 |
+| ignore_iterators | Array | List of iterators to be excluded from the smell check. Includes only `tap` at the moment|

data/docs/Smell-Suppression.md

@@ -1,17 +1,23 @@
 ## Introduction
 
-In some cases, it might be necessary to suppress one or more of `reek`'s smell warnings for a particular method or class. 
+In some cases, it might be necessary to suppress one or more of `reek`'s smell
+warnings for a particular method or class.
 
 Possible reasons for this could be:
 
 * The code is outside of your control and you can't fix it
-* `reek` is not the police. You might have legit reasons why your source code is good as it is.
+* `reek` is not the police. You might have legit reasons why your source code
+  is good as it is.
 
 ## How to disable smell detection
 
-First and foremost, there are the [Basic Smell Options](Basic-Smell-Options.md) you can use.
+There are always the [Basic Smell Options](Basic-Smell-Options.md)
+you can use in your configuration file.
 
-Besides from that, you can use special comments, like so:
+But in this document we would like to focus on a completely different
+way - via special comments.
+
+A simple example:
 
 ```ruby
 # This method smells of :reek:NestedIterators
@@ -20,7 +26,30 @@ def smelly_method foo
 end
 ```
 
-The method `smelly_method` will not be reported. The general pattern is to put the string ':reek:', followed by the smell class, in a comment before the method or class.
+The method `smelly_method` will not be reported. The general pattern is to put
+the string ':reek:', followed by the smell class, in a comment before the
+method or class.
+
+## Extended examples
+
+Multiple smells may be configured for the same method or class:
+
+```ruby
+# :reek:LongParameterList and :reek:NestedIterators
+def many_parameters_it_has foo, bar, baz, qux
+  foo.each {|bar| bar.each {|baz| baz.qux(qux)}}
+end
+```
+
+Or across several lines which is arguably more readable:
+
+```ruby
+# :reek:LongParameterList
+# :reek:NestedIterators
+def many_parameters_it_has foo, bar, baz, qux
+  foo.each {|bar| bar.each {|baz| baz.qux(qux)}}
+end
+```
 
 It is also possible to specify options for a particular smell detector, like so:
 
@@ -30,3 +59,38 @@ def many_parameters_it_has foo, bar, baz, qux
   # ...
 end
 ```
+
+Every configuration setting that you can pass via configuration file you can
+also use via comment.
+
+E.g.:
+
+```ruby
+# :reek:TooManyStatements: { max_statements: 6 }
+def too_many
+  # ...
+end
+
+# :reek:NestedIterators: { max_allowed_nesting: 2 }
+def quax
+  foo.each {|bar| bar.each {|baz| baz.qux(qux)}}
+end
+
+# :reek:DuplicateMethodCall: { max_calls: 3 }
+def quax
+  foo.to_i + foo.to_i + foo.to_i
+end
+```
+
+Keep in mind that there are also smell detectors that operate on a class or
+module level, e.g.:
+
+```ruby
+# :reek:TooManyInstanceVariables: { max_instance_variables: 8 }
+class Klass
+  # ...
+end
+```
+
+To see what smell detector takes what special configuration just check out the
+dedicated documentation for this smell detector.

data/docs/Uncommunicative-Module-Name.md

@@ -20,4 +20,4 @@ Poor names make it hard for the reader to build a mental picture of what's going
 | Option         | Value       | Effect  |
 | ---------------|-------------|---------|
 | `reject` | array of regular expressions | The set of regular expressions that `reek` uses to check for bad names. Defaults to `[/^.$/, /[0-9]$/]`. |
-| `accept` | array of strings or regular expressions | Name that will be accepted (not reported) even if they match one of the `reject` expressions. Defaults to `['Inline::C']`.|
+| `accept` | array of names as strings | List of names that will be accepted (not reported) even if they match one of the `reject` expressions. Empty by default.|

data/docs/Utility-Function.md

@@ -41,4 +41,16 @@ _[Feature Envy](Feature-Envy.md)_ is only triggered if there are some references
 
 ## Configuration
 
-`reek`'s _Utility Function_ detector supports the [Basic Smell Options](Basic-Smell-Options.md).
+`reek`'s _Utility Function_ detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| public_methods_only | Boolean | Disable this smell detector for non-public methods (which means "private" and "protected") |
+
+A sample configuration file would look like this:
+
+```Yaml
+---
+UtilityFunction:
+  public_methods_only: true
+``

data/docs/style-guide.md

@@ -0,0 +1,18 @@
+# Style guide
+
+## Instance variables and getters / setters
+
+We use instance vars only:
+
+- in the constructor
+- for [memoization](http://gavinmiller.io/2013/basics-of-ruby-memoization/)
+
+For everything else we use proper getters / setters.
+
+If possible those should be private. We use the [private_attr](https://github.com/jswanner/private_attr) for this, e.g.:
+
+```Ruby
+private_attr_reader :configuration
+private_attr_writer :failure_message
+private_attr_accessor :examiner
+```

data/docs/templates/default/docstring/html/public_api_marker.erb

@@ -0,0 +1,3 @@
+<div class="note public">
+  <div class="inline"><p>This <%= object.type %> is part of Reek's public API.</p></div>
+</div>

data/docs/templates/default/docstring/setup.rb

@@ -0,0 +1,41 @@
+def init
+  super
+  return unless show_api_marker_section?
+  if sections.first
+    sections.first.place(:api_marker).before(:private)
+  else
+    sections :index, [:api_marker]
+  end
+end
+
+def api_marker
+  return if object.type == :root
+  case api_text
+  when 'public'
+    # erb(:public_api_marker)
+  when 'private'
+    # Let section 'private' handle this.
+  else
+    erb(:private)
+  end
+end
+
+private
+
+def api_text
+  api_text = object.has_tag?(:api) && object.tag(:api).text
+  api_text = 'public' if object.has_tag?(:public)
+  api_text
+end
+
+def show_api_marker_section?
+  return false if object.type == :root
+  case api_text
+  when 'public'
+    false
+  when 'private'
+    false
+  else
+    true
+  end
+end

data/docs/templates/default/fulldoc/html/css/common.css

@@ -0,0 +1 @@
+.note.public { background: #c5ffc5; border-color: #aaecaa; }

data/docs/yard_plugin.rb

@@ -12,3 +12,5 @@ module LocalLinkHelper
 end
 
 YARD::Templates::Template.extra_includes << LocalLinkHelper
+YARD::Tags::Library.define_tag('Guaranteed public API', :public)
+YARD::Templates::Engine.register_template_path File.join(File.dirname(__FILE__), 'templates')

data/features/command_line_interface/smell_selection.feature

@@ -5,6 +5,7 @@ Feature: Smell selection
 
   Scenario: --smell selects a smell to detect
     Given a smelly file called 'smelly.rb'
+    And a configuration file masking some duplication smells called 'config.reek'
     When I run reek --no-line-numbers --smell UncommunicativeMethodName smelly.rb
     Then the exit status indicates smells
     And it reports:

data/features/configuration_files/masking_smells.feature

@@ -45,3 +45,15 @@ Feature: Masking smells using config files
         [5]:Dirty has the variable name '@s' (UncommunicativeVariableName)
         [5]:Dirty#a has the variable name 'x' (UncommunicativeVariableName)
       """
+
+  Scenario: Disable UtilityFunction for non-public methods
+    Given a smelly file called 'smelly.rb' with private, protected and public UtilityFunction methods
+    And a configuration file disabling UtilityFunction for non-public methods called 'config.reek'
+    When I run reek -c config.reek smelly.rb
+    Then the exit status indicates smells
+    And it reports:
+      """
+      smelly.rb -- 1 warning:
+        [3]:Klass#public_method doesn't depend on instance state (maybe move it to another class?) (UtilityFunction)
+      """
+    But it does not report private or protected methods

data/features/samples.feature

@@ -11,7 +11,7 @@ Feature: Basic smell detection
     Then the exit status indicates smells
     And it reports:
     """
-    inline.rb -- 46 warnings:
+    inline.rb -- 47 warnings:
       CompilationError has no descriptive comment (IrresponsibleModule)
       Dir has no descriptive comment (IrresponsibleModule)
       File has no descriptive comment (IrresponsibleModule)
@@ -24,6 +24,7 @@ Feature: Basic smell detection
       Inline::C declares the class variable @@type_map (ClassVariable)
       Inline::C has at least 13 instance variables (TooManyInstanceVariables)
       Inline::C has at least 25 methods (TooManyMethods)
+      Inline::C has the name 'C' (UncommunicativeModuleName)
       Inline::C takes parameters [options, src] to 5 methods (DataClump)
       Inline::C tests $DEBUG at least 7 times (RepeatedConditional)
       Inline::C tests $TESTING at least 4 times (RepeatedConditional)
@@ -53,7 +54,7 @@ Feature: Basic smell detection
       Inline::C#parse_signature has boolean parameter 'raw' (BooleanParameter)
       Inline::C#parse_signature has the variable name 'x' (UncommunicativeVariableName)
       Inline::C#parse_signature is controlled by argument raw (ControlParameter)
-      Inline::C#strip_comments doesn't depend on instance state (UtilityFunction)
+      Inline::C#strip_comments doesn't depend on instance state (maybe move it to another class?) (UtilityFunction)
       Module has no descriptive comment (IrresponsibleModule)
       Module#inline calls Inline.const_get(lang) 2 times (DuplicateMethodCall)
       Module#inline calls options[:testing] 2 times (DuplicateMethodCall)
@@ -103,9 +104,9 @@ Feature: Basic smell detection
       OptionParser#make_switch has the variable name 'v' (UncommunicativeVariableName)
       OptionParser#make_switch performs a nil-check (NilCheck)
       OptionParser#order calls argv[0] 2 times (DuplicateMethodCall)
-      OptionParser#order refers to argv more than self (FeatureEnvy)
+      OptionParser#order refers to argv more than self (maybe move it to another class?) (FeatureEnvy)
       OptionParser#parse calls argv[0] 2 times (DuplicateMethodCall)
-      OptionParser#parse refers to argv more than self (FeatureEnvy)
+      OptionParser#parse refers to argv more than self (maybe move it to another class?) (FeatureEnvy)
       OptionParser#parse_in_order calls $!.set_option(arg, true) 2 times (DuplicateMethodCall)
       OptionParser#parse_in_order calls cb.call(val) 2 times (DuplicateMethodCall)
       OptionParser#parse_in_order calls raise($!.set_option(arg, true)) 2 times (DuplicateMethodCall)
@@ -116,7 +117,7 @@ Feature: Basic smell detection
       OptionParser#parse_in_order contains iterators nested 3 deep (NestedIterators)
       OptionParser#parse_in_order has approx 35 statements (TooManyStatements)
       OptionParser#permute calls argv[0] 2 times (DuplicateMethodCall)
-      OptionParser#permute refers to argv more than self (FeatureEnvy)
+      OptionParser#permute refers to argv more than self (maybe move it to another class?) (FeatureEnvy)
       OptionParser#permute! has approx 6 statements (TooManyStatements)
       OptionParser#program_name is a writable attribute (Attribute)
       OptionParser#release is a writable attribute (Attribute)
@@ -139,15 +140,15 @@ Feature: Basic smell detection
       OptionParser::Completion#complete has boolean parameter 'icase' (BooleanParameter)
       OptionParser::Completion#complete has the variable name 'k' (UncommunicativeVariableName)
       OptionParser::Completion#complete has the variable name 'v' (UncommunicativeVariableName)
-      OptionParser::Completion#complete refers to candidates more than self (FeatureEnvy)
+      OptionParser::Completion#complete refers to candidates more than self (maybe move it to another class?) (FeatureEnvy)
       OptionParser::Completion#convert has unused parameter 'opt' (UnusedParameters)
       OptionParser::List#accept has the parameter name 't' (UncommunicativeParameterName)
-      OptionParser::List#accept refers to pat more than self (FeatureEnvy)
-      OptionParser::List#add_banner refers to opt more than self (FeatureEnvy)
+      OptionParser::List#accept refers to pat more than self (maybe move it to another class?) (FeatureEnvy)
+      OptionParser::List#add_banner refers to opt more than self (maybe move it to another class?) (FeatureEnvy)
       OptionParser::List#complete has 4 parameters (LongParameterList)
       OptionParser::List#complete has boolean parameter 'icase' (BooleanParameter)
       OptionParser::List#reject has the parameter name 't' (UncommunicativeParameterName)
-      OptionParser::List#summarize refers to opt more than self (FeatureEnvy)
+      OptionParser::List#summarize refers to opt more than self (maybe move it to another class?) (FeatureEnvy)
       OptionParser::List#update has 5 parameters (LongParameterList)
       OptionParser::List#update has approx 10 statements (TooManyStatements)
       OptionParser::List#update has the variable name 'o' (UncommunicativeVariableName)
@@ -189,11 +190,11 @@ Feature: Basic smell detection
       RedCloth tests codepre.zero? at least 3 times (RepeatedConditional)
       RedCloth tests href at least 3 times (RepeatedConditional)
       RedCloth tests title at least 4 times (RepeatedConditional)
-      RedCloth#block_markdown_atx refers to text more than self (FeatureEnvy)
+      RedCloth#block_markdown_atx refers to text more than self (maybe move it to another class?) (FeatureEnvy)
       RedCloth#block_markdown_bq has approx 6 statements (TooManyStatements)
       RedCloth#block_markdown_lists has unused parameter 'text' (UnusedParameters)
-      RedCloth#block_markdown_rule doesn't depend on instance state (UtilityFunction)
-      RedCloth#block_markdown_setext refers to text more than self (FeatureEnvy)
+      RedCloth#block_markdown_rule doesn't depend on instance state (maybe move it to another class?) (UtilityFunction)
+      RedCloth#block_markdown_setext refers to text more than self (maybe move it to another class?) (FeatureEnvy)
       RedCloth#block_textile_lists calls depth.last 5 times (DuplicateMethodCall)
       RedCloth#block_textile_lists calls depth.last.length 2 times (DuplicateMethodCall)
       RedCloth#block_textile_lists calls depth[i] 2 times (DuplicateMethodCall)
@@ -204,7 +205,7 @@ Feature: Basic smell detection
       RedCloth#block_textile_lists has approx 21 statements (TooManyStatements)
       RedCloth#block_textile_lists has the variable name 'i' (UncommunicativeVariableName)
       RedCloth#block_textile_lists has the variable name 'v' (UncommunicativeVariableName)
-      RedCloth#block_textile_lists refers to depth more than self (FeatureEnvy)
+      RedCloth#block_textile_lists refers to depth more than self (maybe move it to another class?) (FeatureEnvy)
       RedCloth#block_textile_table contains iterators nested 3 deep (NestedIterators)
       RedCloth#block_textile_table has approx 19 statements (TooManyStatements)
       RedCloth#block_textile_table has the variable name 'x' (UncommunicativeVariableName)
@@ -212,25 +213,25 @@ Feature: Basic smell detection
       RedCloth#blocks has approx 19 statements (TooManyStatements)
       RedCloth#blocks has boolean parameter 'deep_code' (BooleanParameter)
       RedCloth#blocks is controlled by argument deep_code (ControlParameter)
-      RedCloth#blocks refers to blk more than self (FeatureEnvy)
+      RedCloth#blocks refers to blk more than self (maybe move it to another class?) (FeatureEnvy)
       RedCloth#clean_html calls tags[tag] 2 times (DuplicateMethodCall)
       RedCloth#clean_html contains iterators nested 3 deep (NestedIterators)
-      RedCloth#clean_html doesn't depend on instance state (UtilityFunction)
+      RedCloth#clean_html doesn't depend on instance state (maybe move it to another class?) (UtilityFunction)
       RedCloth#clean_html has approx 15 statements (TooManyStatements)
       RedCloth#clean_html has the variable name 'q' (UncommunicativeVariableName)
       RedCloth#clean_html has the variable name 'q2' (UncommunicativeVariableName)
       RedCloth#clean_white_space has approx 7 statements (TooManyStatements)
-      RedCloth#clean_white_space refers to text more than self (FeatureEnvy)
+      RedCloth#clean_white_space refers to text more than self (maybe move it to another class?) (FeatureEnvy)
       RedCloth#filter_html is a writable attribute (Attribute)
       RedCloth#filter_styles is a writable attribute (Attribute)
-      RedCloth#flush_left doesn't depend on instance state (UtilityFunction)
-      RedCloth#footnote_ref doesn't depend on instance state (UtilityFunction)
+      RedCloth#flush_left doesn't depend on instance state (maybe move it to another class?) (UtilityFunction)
+      RedCloth#footnote_ref doesn't depend on instance state (maybe move it to another class?) (UtilityFunction)
       RedCloth#glyphs_textile has approx 10 statements (TooManyStatements)
-      RedCloth#h_align doesn't depend on instance state (UtilityFunction)
+      RedCloth#h_align doesn't depend on instance state (maybe move it to another class?) (UtilityFunction)
       RedCloth#hard_breaks is a writable attribute (Attribute)
-      RedCloth#htmlesc doesn't depend on instance state (UtilityFunction)
+      RedCloth#htmlesc doesn't depend on instance state (maybe move it to another class?) (UtilityFunction)
       RedCloth#htmlesc is controlled by argument mode (ControlParameter)
-      RedCloth#incoming_entities doesn't depend on instance state (UtilityFunction)
+      RedCloth#incoming_entities doesn't depend on instance state (maybe move it to another class?) (UtilityFunction)
       RedCloth#initialize has the variable name 'r' (UncommunicativeVariableName)
       RedCloth#inline contains iterators nested 2 deep (NestedIterators)
       RedCloth#inline_markdown_link has approx 6 statements (TooManyStatements)
@@ -247,16 +248,16 @@ Feature: Basic smell detection
       RedCloth#inline_textile_span contains iterators nested 2 deep (NestedIterators)
       RedCloth#inline_textile_span has approx 9 statements (TooManyStatements)
       RedCloth#inline_textile_span has the variable name 'm' (UncommunicativeVariableName)
-      RedCloth#lT doesn't depend on instance state (UtilityFunction)
+      RedCloth#lT doesn't depend on instance state (maybe move it to another class?) (UtilityFunction)
       RedCloth#lT has the name 'lT' (UncommunicativeMethodName)
       RedCloth#lT is controlled by argument text (ControlParameter)
       RedCloth#lite_mode is a writable attribute (Attribute)
       RedCloth#no_span_caps is a writable attribute (Attribute)
-      RedCloth#no_textile doesn't depend on instance state (UtilityFunction)
+      RedCloth#no_textile doesn't depend on instance state (maybe move it to another class?) (UtilityFunction)
       RedCloth#pba calls $1.length 2 times (DuplicateMethodCall)
       RedCloth#pba has approx 21 statements (TooManyStatements)
       RedCloth#pba is controlled by argument element (ControlParameter)
-      RedCloth#pba refers to text more than self (FeatureEnvy)
+      RedCloth#pba refers to text more than self (maybe move it to another class?) (FeatureEnvy)
       RedCloth#refs_markdown has the variable name 'm' (UncommunicativeVariableName)
       RedCloth#refs_textile has the variable name 'm' (UncommunicativeVariableName)
       RedCloth#retrieve has the variable name 'i' (UncommunicativeVariableName)
@@ -281,6 +282,6 @@ Feature: Basic smell detection
       RedCloth#textile_popup_help has the parameter name 'windowH' (UncommunicativeParameterName)
       RedCloth#textile_popup_help has the parameter name 'windowW' (UncommunicativeParameterName)
       RedCloth#to_html has approx 26 statements (TooManyStatements)
-      RedCloth#v_align doesn't depend on instance state (UtilityFunction)
-    268 total warnings
+      RedCloth#v_align doesn't depend on instance state (maybe move it to another class?) (UtilityFunction)
+    269 total warnings
     """