reek 4.8.1 → 5.0.2

data/lib/reek/context/method_context.rb

@@ -7,7 +7,7 @@ module Reek
     #
     # A context wrapper for any method definition found in a syntax tree.
     #
-    # :reek:Attribute
+    # @quality :reek:Attribute
     class MethodContext < CodeContext
       attr_accessor :visibility
       attr_reader :refs
@@ -35,7 +35,7 @@ module Reek
         local_nodes([:lvar, :lvasgn]).find { |node| node.var_name == param.name }
       end
 
-      # :reek:FeatureEnvy
+      # @quality :reek:FeatureEnvy
       def unused_params
         exp.arguments.reject do |param|
           param.anonymous_splat? ||

data/lib/reek/context/module_context.rb

@@ -73,7 +73,7 @@ module Reek
       #
       # @return true if the module is a namespace module
       #
-      # :reek:FeatureEnvy
+      # @quality :reek:FeatureEnvy
       def namespace_module?
         return false if exp.type == :casgn
         children = exp.direct_children

data/lib/reek/context_builder.rb

@@ -20,9 +20,9 @@ module Reek
   # counting. Ideally `ContextBuilder` would only build up the context tree and leave the
   # statement and reference counting to the contexts.
   #
-  # :reek:TooManyMethods: { max_methods: 31 }
-  # :reek:UnusedPrivateMethod: { exclude: [ !ruby/regexp /process_/ ] }
-  # :reek:DataClump
+  # @quality :reek:TooManyMethods { max_methods: 31 }
+  # @quality :reek:UnusedPrivateMethod { exclude: [ !ruby/regexp /process_/ ] }
+  # @quality :reek:DataClump
   class ContextBuilder
     attr_reader :context_tree
 
@@ -470,7 +470,7 @@ module Reek
       self.class.private_method_defined?(name)
     end
 
-    # :reek:ControlParameter
+    # @quality :reek:ControlParameter
     def increase_statement_count_by(sexp)
       current_context.statement_counter.increase_by sexp
     end
@@ -482,8 +482,8 @@ module Reek
     # Stores a reference to the current context, creates a nested new one,
     # yields to the given block and then restores the previous context.
     #
-    # @param klass [Context::*Context] - context class
-    # @param args - arguments for the class initializer
+    # @param klass [Context::*Context] context class
+    # @param args arguments for the class initializer
     # @yield block
     #
     def inside_new_context(klass, *args)
@@ -497,10 +497,10 @@ module Reek
     # Appends a new child context to the current context but does not change
     # the current context.
     #
-    # @param klass [Context::*Context] - context class
-    # @param args - arguments for the class initializer
+    # @param klass [Context::*Context] context class
+    # @param args arguments for the class initializer
     #
-    # @return [Context::*Context] - the context that was appended
+    # @return [Context::*Context] the context that was appended
     #
     def append_new_context(klass, *args)
       klass.new(*args).tap do |new_context|

data/lib/reek/detector_repository.rb

@@ -44,6 +44,12 @@ module Reek
       end
     end
 
+    # @return [Array<String>] The names of all known SmellDetectors
+    #         e.g. ["BooleanParameter", "ClassVariable"].
+    def self.available_detector_names
+      smell_types.map(&:smell_type)
+    end
+
     private
 
     attr_reader :configuration, :smell_types

data/lib/reek/documentation_link.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Reek
+  # Generate versioned links to our documentation
+  module DocumentationLink
+    HELP_LINK_TEMPLATE = 'https://github.com/troessner/reek/blob/v%<version>s/docs/%<item>s.md'
+
+    module_function
+
+    # Build link to the documentation about the given subject for the current
+    # version of Reek. The subject can be either a smell type like
+    # 'FeatureEnvy' or a general subject like 'Rake Task'.
+    #
+    # @param subject [String]
+    # @return [String] the full URL for the relevant documentation
+    def build(subject)
+      Kernel.format(HELP_LINK_TEMPLATE, version: Version::STRING, item: name_to_param(subject))
+    end
+
+    # Convert the given subject name to a form that is acceptable in a URL.
+    def name_to_param(name)
+      # Splits the subject on the start of capitalized words, optionally
+      # preceded by a space. The space is discarded, the start of the word is
+      # not.
+      name.split(/ *(?=[A-Z][a-z])/).join('-')
+    end
+  end
+end

data/lib/reek/errors/bad_detector_configuration_key_in_comment_error.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 require_relative 'base_error'
+require_relative '../documentation_link'
 
 module Reek
   module Errors
     # Gets raised when trying to configure a detector with an option
     # which is unknown to it.
     class BadDetectorConfigurationKeyInCommentError < BaseError
-      UNKNOWN_SMELL_DETECTOR_MESSAGE = <<-MESSAGE.freeze
+      UNKNOWN_SMELL_DETECTOR_MESSAGE = <<-MESSAGE
 
         Error: You are trying to configure the smell detector '%<detector>s'
         in one of your source code comments with the unknown option %<option>s.
@@ -17,8 +18,8 @@ module Reek
         %<comment>s
 
         Please see the Reek docs for:
-          * how to configure Reek via source code comments: https://github.com/troessner/reek/blob/master/docs/Smell-Suppression.md
-          * what basic options are available: https://github.com/troessner/reek/blob/master/docs/Basic-Smell-Options.md
+          * how to configure Reek via source code comments: #{DocumentationLink.build('Smell Suppression')}
+          * what basic options are available: #{DocumentationLink.build('Basic Smell Options')}
           * what custom options are available by checking the detector specific documentation in /docs
         Update the offensive comment (or remove it if no longer applicable) and re-run Reek.
 

data/lib/reek/errors/bad_detector_in_comment_error.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'base_error'
+require_relative '../documentation_link'
 
 module Reek
   module Errors
@@ -8,7 +9,7 @@ module Reek
     # This might happen for multiple reasons. The users might have a typo in
     # his comment or he might use a detector that does not exist anymore.
     class BadDetectorInCommentError < BaseError
-      UNKNOWN_SMELL_DETECTOR_MESSAGE = <<-MESSAGE.freeze
+      UNKNOWN_SMELL_DETECTOR_MESSAGE = <<-MESSAGE
 
         Error: You are trying to configure an unknown smell detector '%<detector>s' in one
         of your source code comments.
@@ -18,8 +19,8 @@ module Reek
         %<comment>s
 
         Please see the Reek docs for:
-          * how to configure Reek via source code comments: https://github.com/troessner/reek/blob/master/docs/Smell-Suppression.md
-          * what smell detectors are available: https://github.com/troessner/reek/blob/master/docs/Code-Smells.md
+          * how to configure Reek via source code comments: #{DocumentationLink.build('Smell Suppression')}
+          * what smell detectors are available: #{DocumentationLink.build('Code Smells')}
         Update the offensive comment (or remove it if no longer applicable) and re-run Reek.
 
       MESSAGE

data/lib/reek/errors/config_file_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'base_error'
+
+module Reek
+  module Errors
+    # Gets raised when Reek is unable to process the source due to bad config file
+    class ConfigFileError < BaseError
+    end
+  end
+end

data/lib/reek/errors/encoding_error.rb

@@ -6,9 +6,9 @@ module Reek
   module Errors
     # Gets raised when Reek is unable to process the source due to an EncodingError
     class EncodingError < BaseError
-      TEMPLATE = "Source '%<source>s' cannot be processed by Reek due to an encoding error in the source file.".freeze
+      TEMPLATE = "Source '%<source>s' cannot be processed by Reek due to an encoding error in the source file."
 
-      LONG_TEMPLATE = <<-MESSAGE.freeze
+      LONG_TEMPLATE = <<-MESSAGE
         !!!
         %<message>s
 

data/lib/reek/errors/garbage_detector_configuration_in_comment_error.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 require_relative 'base_error'
+require_relative '../documentation_link'
 
 module Reek
   module Errors
     # Gets raised when trying to use a configuration for a detector
     # that can't be parsed into a hash.
     class GarbageDetectorConfigurationInCommentError < BaseError
-      BAD_DETECTOR_CONFIGURATION_MESSAGE = <<-MESSAGE.freeze
+      BAD_DETECTOR_CONFIGURATION_MESSAGE = <<-MESSAGE
 
         Error: You are trying to configure the smell detector '%<detector>s'.
         Unfortunately we cannot parse the configuration you have given.
@@ -17,8 +18,8 @@ module Reek
         %<comment>s
 
         Please see the Reek docs for:
-          * how to configure Reek via source code comments: https://github.com/troessner/reek/blob/master/docs/Smell-Suppression.md
-          * what smell detectors are available: https://github.com/troessner/reek/blob/master/docs/Code-Smells.md
+          * how to configure Reek via source code comments: #{DocumentationLink.build('Smell Suppression')}
+          * what smell detectors are available: #{DocumentationLink.build('Code Smells')}
         Update the offensive comment (or remove it if no longer applicable) and re-run Reek.
 
       MESSAGE

data/lib/reek/errors/incomprehensible_source_error.rb

@@ -6,9 +6,9 @@ module Reek
   module Errors
     # Gets raised when Reek is unable to process the source
     class IncomprehensibleSourceError < BaseError
-      TEMPLATE = 'Source %<source>s cannot be processed by Reek.'.freeze
+      TEMPLATE = 'Source %<source>s cannot be processed by Reek.'
 
-      LONG_TEMPLATE = <<-MESSAGE.freeze
+      LONG_TEMPLATE = <<-MESSAGE
         !!!
         %<message>s
 

data/lib/reek/errors/syntax_error.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'base_error'
+
+module Reek
+  module Errors
+    # Gets raised when Reek is unable to process the source due to a SyntaxError
+    class SyntaxError < BaseError
+      TEMPLATE = "Source '%<source>s' cannot be processed by Reek due to a syntax error in the source file."
+
+      LONG_TEMPLATE = <<-MESSAGE
+        !!!
+        %<message>s
+
+        This is a problem that is outside of Reek's scope and should be fixed by you, the
+        user, in order for Reek being able to continue.
+
+        Exception message:
+
+        %<exception>s
+
+        Original backtrace:
+
+        %<original>s
+
+        !!!
+      MESSAGE
+
+      def initialize(origin:)
+        super format(TEMPLATE, source: origin)
+      end
+
+      def long_message
+        format(LONG_TEMPLATE,
+               message: message,
+               exception: cause.inspect,
+               original: cause.backtrace.join("\n\t"))
+      end
+    end
+  end
+end

data/lib/reek/examiner.rb

@@ -4,6 +4,7 @@ require_relative 'context_builder'
 require_relative 'detector_repository'
 require_relative 'errors/incomprehensible_source_error'
 require_relative 'errors/encoding_error'
+require_relative 'errors/syntax_error'
 require_relative 'source/source_code'
 
 module Reek
@@ -11,6 +12,7 @@ module Reek
   # Applies all available smell detectors to a source.
   #
   # @public
+  # @quality :reek:TooManyInstanceVariables { max_instance_variables: 5 }
   class Examiner
     # Handles no errors
     class NullHandler
@@ -39,26 +41,17 @@ module Reek
                    detector_repository_class: DetectorRepository,
                    error_handler: NullHandler.new)
       @source              = Source::SourceCode.from(source)
+      @origin              = @source.origin
       @smell_types         = detector_repository_class.eligible_smell_types(filter_by_smells)
       @detector_repository = detector_repository_class.new(smell_types: @smell_types,
-                                                           configuration: configuration.directive_for(description))
+                                                           configuration: configuration.directive_for(@origin))
       @error_handler       = error_handler
     end
 
     # @return [String] origin of the source being analysed
     #
     # @public
-    def origin
-      @origin ||= source.origin
-    end
-
-    # @return [String] description of the source being analysed
-    #
-    # @public
-    # @deprecated Use origin
-    def description
-      origin
-    end
+    attr_reader :origin
 
     #
     # @return [Array<SmellWarning>] the smells found in the source
@@ -98,20 +91,22 @@ module Reek
     #
     def run
       wrap_exceptions do
-        examine_tree || report_syntax_errors
+        examine_tree
       end
     rescue StandardError => exception
       raise unless @error_handler.handle exception
       []
     end
 
-    # :reek:TooManyStatements { max_statements: 6 }
+    # @quality :reek:TooManyStatements { max_statements: 6 }
     def wrap_exceptions
       yield
     rescue Errors::BaseError
       raise
     rescue EncodingError
       raise Errors::EncodingError, origin: origin
+    rescue Parser::SyntaxError
+      raise Errors::SyntaxError, origin: origin
     rescue StandardError
       raise Errors::IncomprehensibleSourceError, origin: origin
     end
@@ -121,14 +116,9 @@ module Reek
     end
 
     def examine_tree
-      return unless syntax_tree
       ContextBuilder.new(syntax_tree).context_tree.flat_map do |element|
         detector_repository.examine(element)
       end
     end
-
-    def report_syntax_errors
-      SmellDetectors::Syntax.smells_from_source(source)
-    end
   end
 end

data/lib/reek/rake/task.rb

@@ -33,8 +33,8 @@ module Reek
     #
     # @public
     #
-    # :reek:TooManyInstanceVariables: { max_instance_variables: 6 }
-    # :reek:Attribute
+    # @quality :reek:TooManyInstanceVariables { max_instance_variables: 6 }
+    # @quality :reek:Attribute
     class Task < ::Rake::TaskLib
       # Name of Reek task. Defaults to :reek.
       # @public
@@ -114,7 +114,7 @@ module Reek
           reject(&:empty?)
       end
 
-      # :reek:UtilityFunction
+      # @quality :reek:UtilityFunction
       def sys_call_failed?
         !$CHILD_STATUS.success?
       end

data/lib/reek/report/base_report.rb

@@ -4,8 +4,6 @@ require 'json'
 require 'pathname'
 require 'rainbow'
 
-require_relative 'formatter'
-
 module Reek
   # @public
   module Report
@@ -16,22 +14,20 @@ module Reek
     #
     # @public
     #
-    # :reek:TooManyInstanceVariables: { max_instance_variables: 7 }
+    # @quality :reek:TooManyInstanceVariables { max_instance_variables: 7 }
     class BaseReport
       NO_WARNINGS_COLOR = :green
       WARNINGS_COLOR = :red
 
       # @public
       #
-      # :reek:BooleanParameter
-      def initialize(heading_formatter: Formatter::QuietHeadingFormatter,
-                     report_formatter: Formatter,
+      # @quality :reek:BooleanParameter
+      def initialize(heading_formatter: QuietHeadingFormatter,
                      sort_by_issue_count: false,
-                     warning_formatter: Formatter::SimpleWarningFormatter.new,
-                     progress_formatter: Formatter::ProgressFormatter::Quiet.new(0))
+                     warning_formatter: SimpleWarningFormatter.new,
+                     progress_formatter: ProgressFormatter::Quiet.new(0))
         @examiners           = []
-        @heading_formatter   = heading_formatter.new(report_formatter)
-        @report_formatter    = report_formatter
+        @heading_formatter   = heading_formatter.new
         @progress_formatter  = progress_formatter
         @sort_by_issue_count = sort_by_issue_count
         @total_smell_count   = 0
@@ -58,7 +54,7 @@ module Reek
       end
 
       def smells?
-        total_smell_count > 0
+        total_smell_count.positive?
       end
 
       def smells
@@ -71,7 +67,7 @@ module Reek
 
       private
 
-      attr_reader :examiners, :heading_formatter, :report_formatter,
+      attr_reader :examiners, :heading_formatter,
                   :sort_by_issue_count, :warning_formatter, :progress_formatter
     end
   end

data/lib/reek/report/code_climate/code_climate_configuration.yml

@@ -284,7 +284,7 @@ InstanceVariableAssumption:
     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:
@@ -565,10 +565,10 @@ NilCheck:
     test.rb -- 1 warning:
       [3]:Klass#nil_checker performs a nil-check. (NilCheck)
     ```
-PrimaDonnaMethod:
+MissingSafeMethod:
   remediation_points: 250_000
   content: |
-    A candidate method for the `Prima Donna Method` smell are methods whose names end with an exclamation mark.
+    A candidate method 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 [here](http://dablog.rubypal.com/2007/8/15/bang-methods-or-danger-will-rubyist) ):
 
@@ -576,7 +576,7 @@ PrimaDonnaMethod:
     The ! in method names that end with ! means, “This method is dangerous”—or, more precisely, this method is the “dangerous” version of an otherwise 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 version does not exist and this method is reported as a smell.
+    Such a method is called `Missing Safe Method` if and only if her non-bang version does not exist and this method is reported as a smell.
 
     ## Example
 
@@ -590,7 +590,7 @@ PrimaDonnaMethod:
     end
     ```
 
-    Reek would report `bar!` as `prima donna method` smell but not `foo!`.
+    Reek would report `bar!` as `Missing Safe Method` smell but not `foo!`.
 
     Reek reports this smell only in a class context, not in a module context in order to allow perfectly legit code like this:
 
@@ -612,7 +612,7 @@ PrimaDonnaMethod:
     end
     ```
 
-    In this example, Reek would not report the `prima donna method` smell for the method `foo` of the `Dangerous` module.
+    In this example, Reek would not report the `Missing Safe Method` smell for the method `foo` of the `Dangerous` module.
 RepeatedConditional:
   remediation_points: 400_000
   content: |
@@ -860,7 +860,3 @@ SubclassedFromCoreClass:
     you are gonna have a bad time.
 
     Source: http://words.steveklabnik.com/beware-subclassing-ruby-core-classes
-Syntax:
-  remediation_points: 250_000
-  content: |
-    Check syntax errors.

data/lib/reek/report/documentation_link_warning_formatter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'simple_warning_formatter'
+
+module Reek
+  module Report
+    #
+    # Formatter that adds a link to the docs to the basic message from
+    # SimpleWarningFormatter.
+    #
+    class DocumentationLinkWarningFormatter < SimpleWarningFormatter
+      def format(warning)
+        "#{super} [#{warning.explanatory_link}]"
+      end
+    end
+  end
+end

data/lib/reek/report/heading_formatter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Reek
+  module Report
+    #
+    # Base class for heading formatters.
+    # Is responsible for formatting the heading emitted for each examiner
+    #
+    # @abstract Override {#show_header?} to implement a heading formatter.
+    class HeadingFormatterBase
+      # @quality :reek:UtilityFunction
+      def show_header?(_examiner)
+        raise NotImplementedError
+      end
+
+      def header(examiner)
+        if show_header?(examiner)
+          formatted_header examiner
+        else
+          ''
+        end
+      end
+
+      private
+
+      def formatted_header(examiner)
+        count = examiner.smells_count
+        result = Rainbow("#{examiner.origin} -- ").cyan +
+          Rainbow("#{count} warning").yellow
+        result += Rainbow('s').yellow unless count == 1
+        result
+      end
+    end
+
+    #
+    # Lists out each examiner, even if it has no smell
+    #
+    class VerboseHeadingFormatter < HeadingFormatterBase
+      def show_header?(_examiner)
+        true
+      end
+    end
+
+    #
+    # Lists only smelly examiners
+    #
+    class QuietHeadingFormatter < HeadingFormatterBase
+      # @quality :reek:UtilityFunction
+      def show_header?(examiner)
+        examiner.smelly?
+      end
+    end
+  end
+end

data/lib/reek/report/json_report.rb

@@ -12,7 +12,7 @@ module Reek
     #
     class JSONReport < BaseReport
       def show(out = $stdout)
-        out.print ::JSON.generate smells.map { |smell| warning_formatter.format_hash(smell) }
+        out.print ::JSON.generate smells.map(&:yaml_hash)
       end
     end
   end

data/lib/reek/report/location_formatter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Reek
+  module Report
+    #
+    # Formats the location of a warning as an empty string.
+    #
+    module BlankLocationFormatter
+      module_function
+
+      def format(_warning)
+        ''
+      end
+    end
+
+    #
+    # Formats the location of a warning as an array of line numbers.
+    #
+    module DefaultLocationFormatter
+      module_function
+
+      def format(warning)
+        "#{warning.lines.sort.inspect}:"
+      end
+    end
+
+    #
+    # Formats the location of a warning as a combination of source file name
+    # and line number. In this format, it is not possible to show more than
+    # one line number, so the first number is displayed.
+    #
+    module SingleLineLocationFormatter
+      module_function
+
+      def format(warning)
+        "#{warning.source}:#{warning.lines.min}: "
+      end
+    end
+  end
+end