reek 2.2.1 → 3.0.0

data/docs/Reek-Driven-Development.md

@@ -28,14 +28,6 @@ end
 
 By requiring "reek/spec":http://reek.rubyforge.org/rdoc/classes/Reek/Spec.html you gain access to the `reek` matcher, which returns true if and only if `reek` finds smells in your code. And if the test fails, the matcher produces an error message that includes details of all the smells it found.
 
-Note: if you're on ruby 1.9  and RSpec2 you should include Reek::Spec in the configuration block like so,
-
-```Ruby
-RSpec.configure do |c|
-  c.include(Reek::Spec)
-end
-```
-
 ## assert
 
 If you're not yet into BDD with Rspec, you can still gain the benefits of Reek-driven development using assertions:

data/docs/Utility-Function.md

@@ -2,11 +2,9 @@
 
 ## Introduction
 
-A Utility Function is any instance method that has no dependency on the state of the instance.
+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.
+_Utility Function_ is heavily related to _[Feature Envy](Feature-Envy.md)_, please check out the explanation there why _Utility Function_ is something you should care about.
 
 ## Example
 
@@ -29,7 +27,7 @@ test.rb -- 2 warnings:
 
 ## Current Support in reek
 
-`Utility Function` will warn about any method that:
+_Utility Function_ will warn about any method that:
 
 * is non-empty
 * does not override an inherited method
@@ -37,10 +35,10 @@ test.rb -- 2 warnings:
 * doesn't use any of self's instance variables
 * doesn't use any of self's methods
 
-## Configuration
+## Differences to _Feature Envy_
 
-`reek`'s `Utility Function` detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+_[Feature Envy](Feature-Envy.md)_ is only triggered if there are some references to self and _Utility Function_ is triggered if there are no references to self.
+
+## Configuration
 
-| Option         | Value       | Effect  |
-| ---------------|-------------|---------|
-| `max_helper_calls` |  integer | The maximum number of method calls to other objects allowed within a method. Defaults to 2. |
+`reek`'s _Utility Function_ detector supports the [Basic Smell Options](Basic-Smell-Options.md).

data/features/{ruby_api/api.feature → command_line_interface/basic_usage.feature}

@@ -1,7 +1,7 @@
-Feature: The Reek API maintains backwards compatibility
+Feature: The Reek CLI maintains backwards compatibility
   In order to use Reek without fuss
   As a developer
-  I want to have a stable API
+  I want to have a stable basic command line interface
 
   Scenario: the demo example reports as expected
     Given the smelly file 'demo.rb' from the example in the README

data/features/programmatic_access.feature

@@ -3,12 +3,12 @@ Feature: Using reek programmatically
   As a developer
   I want to be able to use its classes
 
-  Scenario:
+  Scenario: Accessing smells found by an examiner
     Given a smelly file called 'smelly.rb'
     And a file named "examine.rb" with:
       """
       require 'reek'
-      examiner = Reek::Core::Examiner.new(['smelly.rb'])
+      examiner = Reek::Examiner.new(File.new('smelly.rb'))
       examiner.smells.each do |smell|
         puts smell.message
       end
@@ -22,3 +22,22 @@ Feature: Using reek programmatically
       has the name 'm'
       """
 
+  Scenario: Using reek's built-in report classes
+    Given a smelly file called 'smelly.rb'
+    And a file named "examine.rb" with:
+      """
+      require 'reek'
+      examiner = Reek::Examiner.new(File.new('smelly.rb'))
+      report = Reek::Report::TextReport.new
+      report.add_examiner examiner
+      report.show
+      """
+    When I run `ruby examine.rb`
+    Then it reports no errors
+    And it reports:
+      """
+      smelly.rb -- 3 warnings:
+        Smelly#m calls @foo.bar 2 times (DuplicateMethodCall)
+        Smelly#m calls puts(@foo.bar) 2 times (DuplicateMethodCall)
+        Smelly#m has the name 'm' (UncommunicativeMethodName)
+      """

data/features/samples.feature

@@ -9,8 +9,9 @@ Feature: Basic smell detection
     Then the exit status indicates smells
     And it reports:
     """
-    inline.rb -- 43 warnings:
+    inline.rb -- 45 warnings:
       CompilationError has no descriptive comment (IrresponsibleModule)
+      Dir has no descriptive comment (IrresponsibleModule)
       File has no descriptive comment (IrresponsibleModule)
       File#self.write_with_backup has approx 6 statements (TooManyStatements)
       Inline declares the class variable @@directory (ClassVariable)
@@ -50,6 +51,7 @@ Feature: Basic smell detection
       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)
+      Module has no descriptive comment (IrresponsibleModule)
       Module#inline calls Inline.const_get(lang) 2 times (DuplicateMethodCall)
       Module#inline calls options[:testing] 2 times (DuplicateMethodCall)
       Module#inline has approx 12 statements (TooManyStatements)

data/lib/reek.rb

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

data/lib/reek/{core → ast}/ast_node_class_map.rb

@@ -1,31 +1,31 @@
-require_relative 'ast_node'
-require_relative '../sexp/sexp_node'
-require_relative '../sexp/sexp_extensions'
+require_relative 'node'
+require_relative 'sexp_extensions'
 
 module Reek
-  module Core
+  module AST
     # Maps AST node types to sublasses of ASTNode extended with the relevant
     # utility modules.
+    #
+    # @api private
     class ASTNodeClassMap
       def initialize
         @klass_map = {}
       end
 
       def klass_for(type)
-        @klass_map[type] ||= Class.new(ASTNode).tap do |klass|
+        @klass_map[type] ||= Class.new(Node).tap do |klass|
           extension = extension_map[type]
           klass.send :include, extension if extension
-          klass.send :include, Sexp::SexpNode
         end
       end
 
       def extension_map
         @extension_map ||=
           begin
-            assoc = Sexp::SexpExtensions.constants.map do |const|
+            assoc = SexpExtensions.constants.map do |const|
               [
                 const.to_s.sub(/Node$/, '').downcase.to_sym,
-                Sexp::SexpExtensions.const_get(const)
+                SexpExtensions.const_get(const)
               ]
             end
             Hash[assoc]

data/lib/reek/{sexp/sexp_node.rb → ast/node.rb}

@@ -1,10 +1,47 @@
+require 'parser'
+
 module Reek
-  module Sexp
-    #
-    # Extensions to +Sexp+ to allow +TreeWalker+ to navigate the abstract
-    # syntax tree more easily.
+  # @api private
+  module AST
+    # Base class for AST nodes extended with utility methods. Contains some
+    # methods to ease the transition from Sexp to AST::Node.
     #
-    module SexpNode
+    # @api private
+    class Node < ::Parser::AST::Node
+      attr_reader :parent
+
+      def initialize(type, children = [], options = {})
+        @comments = options.fetch(:comments, [])
+        @parent   = options.fetch(:parent, nil)
+        super
+      end
+
+      def full_comment
+        @comments.map(&:text).join("\n")
+      end
+
+      def leading_comment
+        line = location.line
+        comment_lines = @comments.select do |comment|
+          comment.location.line < line
+        end
+        comment_lines.map(&:text).join("\n")
+      end
+
+      # @deprecated
+      def [](index)
+        elements[index]
+      end
+
+      def line
+        loc.line
+      end
+
+      # @deprecated
+      def first
+        type
+      end
+
       #
       # Carries out a depth-first traversal of this syntax tree, yielding
       # every Sexp of type `target_type`. The traversal ignores any node
@@ -84,7 +121,11 @@ module Reek
       private
 
       def each_sexp
-        children.each { |elem| yield elem if elem.is_a? AST::Node }
+        children.each { |elem| yield elem if elem.is_a? ::Parser::AST::Node }
+      end
+
+      def elements
+        [type, *children]
       end
     end
   end

data/lib/reek/{core → ast}/object_refs.rb

@@ -1,8 +1,9 @@
 module Reek
-  module Core
+  module AST
     #
     # Manages and counts the references out of a method to other objects.
     #
+    # @api private
     class ObjectRefs  # :nodoc:
       def initialize
         @refs = Hash.new(0)

data/lib/reek/{core → ast}/reference_collector.rb

@@ -1,9 +1,10 @@
 module Reek
-  module Core
+  module AST
     #
     # Locates references to the current object within a portion
     # of an abstract syntax tree.
     #
+    # @api private
     class ReferenceCollector
       STOP_NODES = [:class, :module, :def, :defs]
 

data/lib/reek/{sexp → ast}/sexp_extensions.rb

@@ -1,12 +1,12 @@
-require_relative 'sexp_node'
-require_relative '../core/reference_collector'
+require_relative 'reference_collector'
 
 module Reek
-  module Sexp
+  module AST
     #
     # Extension modules providing utility methods to ASTNode objects, depending
     # on their type.
     #
+    # @api private
     module SexpExtensions
       # Base module for utility methods for argument nodes.
       module ArgNodeBase
@@ -264,7 +264,12 @@ module Reek
         end
 
         def depends_on_instance?
-          Core::ReferenceCollector.new(self).num_refs_to_self > 0
+          ReferenceCollector.new(self).num_refs_to_self > 0
+        end
+
+        def singleton_method?
+          # This catches the case where methods are defined within the "class << self" syntax.
+          parent.type == :sclass if parent
         end
       end
 
@@ -327,7 +332,7 @@ module Reek
         def name() self[1] end
 
         def simple_name
-          name.is_a?(AST::Node) ? name.simple_name : name
+          name.is_a?(::Parser::AST::Node) ? name.simple_name : name
         end
 
         def full_name(outer)

data/lib/reek/{sexp → ast}/sexp_formatter.rb

@@ -4,19 +4,21 @@ Reek::CLI::Silencer.silently do
 end
 
 module Reek
-  module Sexp
+  module AST
     #
     # Formats snippets of syntax tree back into Ruby source code.
     #
-    # :reek:DuplicateMethodCall { max_calls: 2 } is ok for lines.first
+    # @api private
     class SexpFormatter
       # Formats the given sexp.
       #
-      # sexp - S-expression of type AST::Node or something that is at least to_s-able.
+      # @param [AST::Node, #to_s] sexp - The expression to format
       #
-      # Returns a formatted string representation.
+      # @return [String] a formatted string representation.
+      #
+      # :reek:DuplicateMethodCall { max_calls: 2 } is ok for lines.first
       def self.format(sexp)
-        return sexp.to_s unless sexp.is_a? AST::Node
+        return sexp.to_s unless sexp.is_a? ::Parser::AST::Node
         lines = Unparser.unparse(sexp).split "\n"
         case lines.length
         when 1 then lines.first

data/lib/reek/cli/application.rb

@@ -9,6 +9,7 @@ module Reek
     # This is the entry point for all invocations of Reek from the
     # command line.
     #
+    # @api private
     class Application
       STATUS_SUCCESS = 0
       STATUS_ERROR   = 1

data/lib/reek/cli/command.rb

@@ -3,6 +3,7 @@ module Reek
     #
     # Base class for all commands
     #
+    # @api private
     class Command
       attr_reader :options
 

data/lib/reek/cli/input.rb

@@ -1,8 +1,11 @@
+require_relative '../source/source_locator'
+
 module Reek
   module CLI
     #
     # CLI Input utility
     #
+    # @api private
     module Input
       def sources
         if no_source_files_given?
@@ -37,7 +40,7 @@ module Reek
       end
 
       def source_from_pipe
-        [Source::SourceCode.from($stdin)]
+        [$stdin]
       end
     end
   end

data/lib/reek/cli/option_interpreter.rb

@@ -1,16 +1,17 @@
 require 'forwardable'
 require_relative 'input'
-require_relative 'report/report'
-require_relative 'report/formatter'
-require_relative 'report/heading_formatter'
+require_relative '../report/report'
+require_relative '../report/formatter'
+require_relative '../report/heading_formatter'
 
 module Reek
   module CLI
     #
     # Interprets the options set from the command line
     #
+    # @api private
     class OptionInterpreter
-      include CLI::Input
+      include Input
 
       extend Forwardable
 
@@ -30,6 +31,7 @@ module Reek
             heading_formatter: heading_formatter)
       end
 
+      # TODO: Move report type mapping into Report
       def report_class
         case @options.report_format
         when :yaml

data/lib/reek/cli/options.rb

@@ -9,7 +9,8 @@ module Reek
     #
     # Parses the command line
     #
-    # See docs/Command-Line-Options for details.
+    # See {file:docs/Command-Line-Options.md} for details.
+    # @api private
     class Options
       def initialize(argv = [])
         @argv    = argv

data/lib/reek/cli/reek_command.rb

@@ -1,5 +1,5 @@
 require_relative 'command'
-require_relative '../core/examiner'
+require_relative '../examiner'
 
 module Reek
   module CLI
@@ -7,10 +7,11 @@ module Reek
     # A command to collect smells from a set of sources and write them out in
     # text report format.
     #
+    # @api private
     class ReekCommand < Command
       def execute(app)
         @options.sources.each do |source|
-          reporter.add_examiner Core::Examiner.new(source, smell_names)
+          reporter.add_examiner Examiner.new(source, smell_names)
         end
         reporter.smells? ? app.report_smells : app.report_success
         reporter.show

data/lib/reek/cli/silencer.rb

@@ -1,6 +1,7 @@
 module Reek
   module CLI
     # CLI silencer
+    # @api private
     module Silencer
       def self.silently
         old_verbose, $VERBOSE = $VERBOSE, nil

data/lib/reek/{core → cli}/warning_collector.rb

@@ -1,10 +1,11 @@
 require 'set'
 
 module Reek
-  module Core
+  module CLI
     #
     # Collects and sorts smells warnings.
     #
+    # @api private
     class WarningCollector
       def initialize
         @warnings = Set.new