reek 2.1.0 → 2.2.0

data/docs/Uncommunicative-Method-Name.md

@@ -0,0 +1,24 @@
+# Uncommunicative Method Name
+
+## Introduction
+
+An `Uncommunicative Method Name` is a method name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in reek
+
+`Uncommunicative Method Name` checks for:
+
+* 1-character names
+* any name ending with a number
+* camelCaseVariableNames
+
+## Configuration
+
+`reek`'s Uncommunicative Method Name detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| `reject` | array of regular expressions | The set of regular expressions that `reek` uses to check for bad names. Defaults to `[/^[a-z]$/, /[0-9]$/, /[A-Z]/]`. |
+| `accept` | array of strings or regular expressions | Name that will be accepted (not reported) even if they match one of the `reject` expressions. |

data/docs/Uncommunicative-Module-Name.md

@@ -0,0 +1,23 @@
+# Uncommunicative Module Name
+
+## Introduction
+
+An `Uncommunicative Module Name` is a module name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in reek
+
+`Uncommunicative Module Name` checks for:
+
+* 1-character names
+* any name ending with a number
+
+## Configuration
+
+`reek`'s `Uncommunicative Module Name` detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| 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']`.|

data/docs/Uncommunicative-Name.md

@@ -0,0 +1,16 @@
+# Uncommunicative Name
+
+## Introduction
+
+An `Uncommunicative Name` is a name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in Reek
+
+`reek` offers four related checks:
+
+* [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)

data/docs/Uncommunicative-Parameter-Name.md

@@ -0,0 +1,24 @@
+# Uncommunicative Parameter Name
+
+## Introduction
+
+An `Uncommunicative Parameter Name` is a parameter name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in reek
+
+`Uncommunicative Parameter Name` checks for:
+
+* 1-character names
+* any name ending with a number
+* camelCaseVariableNames
+
+## Configuration
+
+`reek`'s Uncommunicative Parameter Name detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| 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]$/, /[A-Z]/]@. |
+| `accept` | array of strings or regular expressions | Name that will be accepted (not reported) even if they match one of the `reject` expressions. |

data/docs/Uncommunicative-Variable-Name.md

@@ -0,0 +1,24 @@
+# Uncommunicative Variable Name
+
+## Introduction
+
+An `Uncommunicative Variable Name` is a variable name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in Reek
+
+`Uncommunicative Variable Name` checks for:
+
+* 1-character names
+* any name ending with a number
+* camelCaseVariableNames
+
+## Configuration
+
+`reek`'s `Uncommunicative Variable Name` detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| 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]$/, /[A-Z]/]`. |
+| `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 @['_']@.|

data/docs/Unused-Parameters.md

@@ -0,0 +1,27 @@
+## Introduction
+
+`Unused Parameter` refers to methods with parameters that are unused in scope of the method.
+
+Having unused parameters in a method is code smell because leaving dead code in a method can never improve the method and it makes the code confusing to read. 
+
+## Example
+
+Given:
+
+```Ruby
+class Klass
+  def unused_parameters(x,y,z)
+    puts x,y # but not z
+  end
+end
+```
+
+`reek` would emit the following warning:
+
+```
+[2]:Klass#unused_parameters has unused parameter 'z' (UnusedParameters)
+```
+
+## Configuration
+
+`Unused Parameter` offers the [Basic Smell Options](Basic-Smell-Options.md).

data/docs/Utility-Function.md

@@ -0,0 +1,46 @@
+# Utility Function
+
+## Introduction
+
+A Utility Function is any instance method that has no dependency on the state of the instance.
+
+A Utility Function reduces the code’s ability to communicate intent: code that “belongs” on one class but which is located in another can be hard to find, and may upset the “System of Names” in the host class. A Utility Function also affects the design’s flexibility: A code fragment that is in the wrong class creates couplings that may not be natural within the application’s domain, and creates a loss of cohesion in the unwilling host class.
+
+A Utility Function often arises because it must manipulate other objects (usually its arguments) to get them into a useful form, and one force preventing them (the arguments) doing this themselves is that the common knowledge lives outside the arguments, or the arguments are of too basic a type to justify extending that type. Therefore there must be something which 'knows' about the contents or purposes of the arguments.  That thing would have to be more than just a basic type, because the basic types are either containers which don't know about their contents, or they are single objects which can't capture their relationship with their fellows of the same type. So, this thing with the extra knowledge should be reified into a class, and the utility method will most likely belong there.
+
+## Example
+
+Given
+
+```Ruby
+class UtilityFunction
+  def showcase(argument)
+    argument.to_s + argument.to_i
+  end
+end
+```
+
+`reek` would report:
+
+```
+test.rb -- 2 warnings:
+  [2]:UtilityFunction#showcase doesn't depend on instance state (UtilityFunction)
+```
+
+## Current Support in reek
+
+`Utility Function` will warn about any method that:
+
+* is non-empty
+* does not override an inherited method
+* calls at least one method on another object
+* doesn't use any of self's instance variables
+* doesn't use any of self's methods
+
+## Configuration
+
+`reek`'s `Utility Function` detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| `max_helper_calls` |  integer | The maximum number of method calls to other objects allowed within a method. Defaults to 2. |

data/docs/Versioning-Policy.md

@@ -0,0 +1,7 @@
+# Versioning Policy
+
+* CLI interface: Adding options is a non-breaking change, and would warrant an update of the minor version. Removing options is a breaking change and requires a major version update (we did this going to reek 2). Adding a report format probably also warrents a minor version upgrade.
+* API: We haven't really defined a 'public' API for using Reek programmatically, and we've only just started testing it. So, this is basically a blank slate at the moment. We will work on this as a part of the reek 3 release.
+* List of detected smells: Adding a smell warrants a minor release, removing a smell is a breaking change. This makes sense if you consider that the CLI allows running a single smell detector.
+* Consistency of detected smells: This is very hard to guarantee. If we fix a bug in one of the detectors, some fragrant code may become smelly, or vice versa. Right now we don't bother with this.
+* Smell configuration: The detectors are quite tolerant regarding configuration options that they don't recognize, so we regard any change here as only requiring a minor release.

data/docs/YAML-Reports.md

@@ -0,0 +1,111 @@
+# YAML Reports
+
+## Introduction
+
+`Reek`'s `--yaml` option writes on $stdout a YAML dump of the smells found. Each reported smell has a number of standard fields and a number of fields that are specific to the smell's type. The common fields are as follows:
+
+| Field         | Type       | Value  |
+| ---------------|-------------|---------|
+| source | string | The name of the source file containing the smell, or `$stdin` |
+| lines | array | The source file line number(s) that contribute to this smell |
+| context | string | The name of the class, module or method containing the smell |
+| class | string | The class to which this smell belongs |
+| subclass | string | This smell's subclass within the above class |
+| message | string | The message that would have been printed in a standard Reek report |
+| is_active | boolean | `false` if the smell is masked by a config file; `true` otherwise |
+
+All of these fields are grouped into hashes `location`, `smell` and `status` (see the examples below).
+
+## Examples
+
+Duplication:
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: spec/samples/masked/dirty.rb
+    lines: 
+    - 5
+    - 7
+    context: Dirty#a
+  smell: 
+    class: Duplication
+    subclass: DuplicateMethodCall
+    occurrences: 2
+    call: puts(@s.title)
+    message: calls puts(@s.title) twice
+  status:
+    is_active: true
+</pre>
+
+[Nested Iterators](Nested-Iterators.md):
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: spec/samples/masked/dirty.rb
+    lines: 
+    - 5
+    context: Dirty#a
+  smell: 
+    class: NestedIterators
+    subclass: ""
+    depth: 2
+    message: contains iterators nested 2 deep
+  status:
+    is_active: true
+</pre>
+
+[Uncommunicative Method Name](Uncommunicative-Method-Name.md):
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: spec/samples/masked/dirty.rb
+    lines: 
+    - 3
+    context: Dirty#a
+  smell: 
+    class: UncommunicativeName
+    subclass: UncommunicativeMethodName
+    method_name: a
+    message: has the name 'a'
+  status:
+    is_active: false
+</pre>
+
+[Uncommunicative Variable Name](Uncommunicative-Variable-Name.md):
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: spec/samples/masked/dirty.rb
+    lines: 
+    - 5
+    context: Dirty#a
+  smell: 
+    class: UncommunicativeName
+    subclass: UncommunicativeVariableName
+    variable_name: x
+    message: has the variable name 'x'
+  status:
+    is_active: true
+</pre>
+
+[Control Couple](Control-Couple.md):
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: $stdin
+    lines: 
+    - 2
+    context: Turn#fred
+  smell: 
+    class: ControlCouple
+    subclass: BooleanParameter
+    parameter: arg
+    message: has boolean parameter 'arg'
+  status:
+    is_active: true
+</pre>

data/docs/yard_plugin.rb

@@ -0,0 +1,14 @@
+require 'yard'
+
+# Template helper to modify processing of links in HTML generated from our
+# markdown files.
+module LocalLinkHelper
+  # Rewrites links to (assumed local) markdown files so they're processed as
+  # {file: } directives.
+  def resolve_links(text)
+    text = text.gsub(%r{<a href="([^"]*.md)">([^<]*)</a>}, '{file:\1 \2}')
+    super text
+  end
+end
+
+YARD::Templates::Template.extra_includes << LocalLinkHelper

data/features/command_line_interface/options.feature

@@ -39,6 +39,7 @@ Feature: Reek can be controlled using command-line options
                                              text (default)
                                              yaml
                                              json
+                                             xml
 
       Text format options:
               --[no-]color                 Use colors for the output (default: true)

data/features/programmatic_access.feature

@@ -8,7 +8,7 @@ Feature: Using reek programmatically
     And a file named "examine.rb" with:
       """
       require 'reek'
-      examiner = Reek::Examiner.new(['smelly.rb'])
+      examiner = Reek::Core::Examiner.new(['smelly.rb'])
       examiner.smells.each do |smell|
         puts smell.message
       end

data/features/samples.feature

@@ -17,7 +17,7 @@ Feature: Basic smell detection
       Inline declares the class variable @@rootdir (ClassVariable)
       Inline#self.rootdir calls env.nil? 2 times (DuplicateMethodCall)
       Inline#self.rootdir has approx 8 statements (TooManyStatements)
-      Inline#self.rootdir performs a nil-check. (NilCheck)
+      Inline#self.rootdir performs a nil-check (NilCheck)
       Inline::C declares the class variable @@type_map (ClassVariable)
       Inline::C has at least 13 instance variables (TooManyInstanceVariables)
       Inline::C takes parameters [options, src] to 5 methods (DataClump)
@@ -101,7 +101,7 @@ Feature: Basic smell detection
       OptionParser#make_switch has the variable name 'q' (UncommunicativeVariableName)
       OptionParser#make_switch has the variable name 's' (UncommunicativeVariableName)
       OptionParser#make_switch has the variable name 'v' (UncommunicativeVariableName)
-      OptionParser#make_switch performs a nil-check. (NilCheck)
+      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#parse calls argv[0] 2 times (DuplicateMethodCall)
@@ -119,7 +119,7 @@ Feature: Basic smell detection
       OptionParser#permute refers to argv more than self (FeatureEnvy)
       OptionParser#permute! has approx 6 statements (TooManyStatements)
       OptionParser#search has the variable name 'k' (UncommunicativeVariableName)
-      OptionParser#self.inc performs a nil-check. (NilCheck)
+      OptionParser#self.inc performs a nil-check (NilCheck)
       OptionParser#summarize has 4 parameters (LongParameterList)
       OptionParser#summarize has the variable name 'l' (UncommunicativeVariableName)
       OptionParser#summarize is controlled by argument blk (ControlParameter)

data/lib/reek.rb

@@ -2,5 +2,5 @@
 # Reek's core functionality
 #
 require_relative 'reek/version'
-require_relative 'reek/examiner'
-require_relative 'reek/smell_warning'
+require_relative 'reek/core/examiner'
+require_relative 'reek/smells/smell_warning'

data/lib/reek/cli/input.rb

@@ -29,11 +29,11 @@ module Reek
       end
 
       def working_directory_as_source
-        Source::SourceLocator.new(['.']).all_sources
+        Source::SourceLocator.new(['.']).sources
       end
 
       def sources_from_argv
-        Source::SourceLocator.new(@argv).all_sources
+        Source::SourceLocator.new(@argv).sources
       end
 
       def source_from_pipe

data/lib/reek/cli/option_interpreter.rb

@@ -38,6 +38,8 @@ module Reek
           Report::JSONReport
         when :html
           Report::HTMLReport
+        when :xml
+          Report::XMLReport
         else # :text
           Report::TextReport
         end

data/lib/reek/cli/options.rb

@@ -9,11 +9,13 @@ module Reek
     #
     # Parses the command line
     #
+    # See docs/Command-Line-Options for details.
     class Options
-      def initialize(argv)
+      def initialize(argv = [])
         @argv    = argv
         @parser  = OptionParser.new
-        @options = OpenStruct.new(colored: true, smells_to_detect: [])
+        @options = OpenStruct.new(colored: color_support?,
+                                  smells_to_detect: [])
         set_up_parser
       end
 
@@ -26,6 +28,10 @@ module Reek
 
       private
 
+      def color_support?
+        $stdout.tty?
+      end
+
       def set_up_parser
         set_banner
         set_configuration_options
@@ -53,9 +59,9 @@ module Reek
       def set_alternative_formatter_options
         @parser.separator "\nReport format:"
         @parser.on(
-          '-f', '--format FORMAT', [:html, :text, :yaml, :json],
+          '-f', '--format FORMAT', [:html, :text, :yaml, :json, :xml],
           'Report smells in the given format:',
-          '  html', '  text (default)', '  yaml', '  json'
+          '  html', '  text (default)', '  yaml', '  json', '  xml'
         ) do |opt|
           @options.report_format = opt
         end