snoot 0.1.0

data/data/reek_docs/Control-Parameter.md

@@ -0,0 +1,32 @@
+# Control Parameter
+
+## Introduction
+
+_Control Parameter_ is a case of [Control Couple](Control-Couple.md).
+
+## Example
+
+A simple example would be the `quoted` parameter in the following method:
+
+```ruby
+def write(quoted)
+  if quoted
+    write_quoted @value
+  else
+    write_unquoted @value
+  end
+end
+```
+
+Fixing those problems is out of the scope of this document but an easy solution
+could be to remove the `write` method altogether and to move the calls to
+`write_quoted` and `write_unquoted` to the caller of `write`.
+
+## Current Support in Reek
+
+Reek warns about _Control Parameter_ when a method parameter or block parameter is
+the tested value in a conditional statement.
+
+## Configuration
+
+_Control Parameter_ supports the [Basic Smell Options](Basic-Smell-Options.md).

data/data/reek_docs/Data-Clump.md

@@ -0,0 +1,46 @@
+# Data Clump
+
+## Introduction
+
+In general, a _Data Clump_ occurs when the same two or three items frequently
+appear together in classes and parameter lists, or when a group of instance
+variable names start or end with similar substrings.
+
+The recurrence of the items often means there is duplicate code spread around to handle them. There may be an abstraction missing from the code, making the system harder to understand.
+
+## Example
+
+Given
+
+```ruby
+class Dummy
+  def x(y1,y2); end
+  def y(y1,y2); end
+  def z(y1,y2); end
+end
+```
+
+Reek would emit the following warning:
+
+```
+test.rb -- 1 warning:
+  [2, 3, 4]:Dummy takes parameters [y1, y2] to 3 methods (DataClump)
+```
+
+A possible way to fix this problem (quoting from [Martin Fowler](http://martinfowler.com/bliki/DataClump.html)):
+
+> The first step is to replace data clumps with objects and use the objects whenever you see them. An immediate benefit is that you'll shrink some parameter lists. The interesting stuff happens as you begin to look for behavior to move into the new objects.
+
+## Current Support in Reek
+
+Reek looks for a group of two or more parameters with the same names that are expected by three or more methods of a class.
+
+## Configuration
+
+Reek's _Data Clump_ detector offers the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option           | Value       | Effect  |
+| -----------------|-------------|---------|
+| `max_copies`     | integer | The maximum number of methods that are permitted to take the same group of parameters. Defaults to 2. |
+| `min_clump_size` | integer | The smallest number of parameters that can be reported as a clump. Defaults to 2. |
+

data/data/reek_docs/Duplicate-Method-Call.md

@@ -0,0 +1,264 @@
+# Duplicate Method Call
+
+## Introduction
+
+Duplication occurs when two fragments of code look nearly identical, or when two fragments of code have nearly identical effects at some conceptual level.
+
+Let's look at an example that is quite common in the Rails world:
+
+```ruby
+def not_production?
+  Rails.env.development? || Rails.env.test?
+end  
+```
+
+While this duplicate usage of `Rails.env` might seem innocuous there are 2 problems with it:
+
+1.) Efficiency
+
+```ruby
+Rails.env.development? || Rails.env.test?
+```
+
+is not as efficient as it could be. If the call to `env` is not memoized your basically paying twice in terms of computation for something that you should only pay once.
+
+Here
+
+```ruby
+Rails.env.development? || Rails.env.test?
+```
+
+you have 4 method calls while here:
+
+```ruby
+env = Rails.env
+env.development? || env.test?
+```
+
+you have one assignment (which is very cheap in terms of computation) and 3 method calls.
+The difference might not be much here but just imagine you're writing a high performance app or you doing some expensive database calls in each method call.
+
+It doesn't really matter though if the efficiency difference is significant. This is a matter of principle - we believe that being efficient is one of the vital traits of good software.
+
+2.) Maintainability
+
+The second point is a bit more subtle. This
+
+```ruby
+env = Rails.env
+env.development? || env.test?
+```
+
+is a lot more intention revealing than 
+
+```ruby
+Rails.env.development? || Rails.env.test?
+```
+
+Here
+
+```ruby
+env = Rails.env
+env.development? || env.test?
+```
+
+I'm very clear on what I do: I get the environment and then I run some checks on it.
+
+Here
+
+```ruby
+Rails.env.development? || Rails.env.test?
+```
+
+I'm not very clear on what I do and it requires quite more mental effort: Ok, so I'm talking to Rails, getting the environment and then running a check on it ...or .....oh, I get the same Rails constant again, get the same environment and run another check on it.
+
+## Example
+
+Here's a very much simplified and contrived example. The following method will report a warning:
+
+```ruby
+def double_thing
+  @other.thing + @other.thing
+end
+```
+
+One quick approach to silence Reek would be to refactor the code thus:
+
+```ruby
+def double_thing
+  thing = @other.thing
+  thing + thing
+end
+```
+
+A slightly different approach would be to replace all calls in `double_thing` by calls to `thing`:
+
+```ruby
+class Other
+  def double_thing
+    thing + thing
+  end
+
+  def thing
+    @other.thing
+  end
+end
+```
+
+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/).
+
+## 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
+
+Reek's Duplicate Method Call detector currently offers the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+Option | Value | Effect
+-------|-------|-------
+`max_calls` |  integer | The maximum number of duplicate calls allowed within a method. Defaults to 1.
+`allow_calls` | an array of strings or regular expressions | Ignores any context who matches it |
+
+## Example configuration
+
+### Adjusting `max_calls`
+
+Imagine code like this:
+
+```ruby
+class Alfa
+  def bravo
+    charlie.delta
+    charlie.delta
+  end
+end
+```
+
+This would report:
+
+>>
+src.rb -- 1 warning:
+  [4, 5]:DuplicateMethodCall: Alfa#bravo calls 'charlie.delta' 2 times
+
+If you want to allow those double calls here you can disable it in 2 different ways:
+
+1.) Via source code comment:
+
+```ruby
+class Alfa
+  # :reek:DuplicateMethodCall { max_calls: 2 }
+  def bravo
+    charlie.delta
+    charlie.delta
+  end
+end
+```
+
+2.) Via configuration file:
+
+```yaml
+DuplicateMethodCall:
+  max_calls: 2
+```
+
+Note though that the latter way will set `max_calls` to 2 for all instances
+of the smell detector which might not be what you want - in this case
+you'll have to use source code comments.
+
+### Adjusting `allow_calls`
+
+Imagine code like this:
+
+```ruby
+class Alfa
+  def bravo
+    charlie.delta
+    charlie.delta
+    echo.foxtrot
+    echo.foxtrot
+  end
+end
+```
+
+This would report:
+
+>>
+src.rb -- 2 warnings:
+  [4, 5]:DuplicateMethodCall: Alfa#bravo calls charlie.delta 2 times
+  [6, 7]:DuplicateMethodCall: Alfa#bravo calls echo.foxtrot 2 times
+
+So let's say you're ok with the `echo.foxtrot` calls you can stop reporting them like this:
+
+1.) Via source code comment:
+
+```ruby
+class Alfa
+  # :reek:DuplicateMethodCall { allow_calls: ['echo.foxtrot'] }
+  def bravo
+    charlie.delta
+    charlie.delta
+    echo.foxtrot
+    echo.foxtrot
+  end
+end
+```
+
+2.) Via configuration file:
+
+```yaml
+DuplicateMethodCall:
+  allow_calls:
+  - 'echo.foxtrot'
+```
+
+Note though that the latter way will allow those calls across your source code which might not be what you want.
+In this case you'll have to use source code comments.

data/data/reek_docs/Feature-Envy.md

@@ -0,0 +1,93 @@
+# Feature Envy
+
+## Introduction
+
+_Feature Envy_ occurs when a code fragment references another object more often than it references itself, or when several clients do the same series of manipulations on a particular type of object.
+
+_Feature Envy_ 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.
+
+_Feature Envy_ 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.
+
+_Feature Envy_ 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
+
+Running Reek on:
+
+```ruby
+class Warehouse
+  def sale_price(item)
+    (item.price - item.rebate) * @vat
+  end
+end
+```
+
+would report:
+
+```bash
+Warehouse#sale_price refers to item more than self (FeatureEnvy)
+```
+
+since this:
+
+```ruby
+(item.price - item.rebate)
+```
+
+belongs to the Item class, not the Warehouse.
+
+## Current Support in Reek
+
+_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.
+
+## Configuration
+
+_Feature Envy_ supports the [Basic Smell Options](Basic-Smell-Options.md).

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

@@ -0,0 +1,144 @@
+## How to write new detectors
+
+### Outline what you have in mind
+
+Before starting to code you should discuss the overall idea for your new smell detector with
+us in a corresponding github issue.
+We all should have a solid understanding of what this detector actually reports, the edge cases
+it covers and the overall rationale behind it.
+
+### Structure
+
+All smell detectors reside in `lib/reek/smell_detectors` and have the following base structure:
+
+```ruby
+require_relative 'base_detector'
+require_relative 'smell_warning'
+
+module Reek
+  module SmellDetectors
+    #
+    # Here goes your introduction for this detector.
+    #
+    # See {file:docs/Your-Detector.md} for details.
+    class YourDetector < BaseDetector
+      def self.contexts
+        [:class] # In case you're operating on class contexts only - just an example.
+      end
+
+      #
+      # Here you should document what you expect the detector's context to look
+      # like.
+      #
+      # @return [Array<SmellWarning>]
+      #
+      def sniff
+        # "found_smells" below is just an abstraction for
+        # "find the smells in question" and iterate over them.
+        # This can just be a method but it can also be a more sophisticated set up.
+        # Check out other smell detectors to get a feeling for what to do here.
+        found_smells.map do |smell|
+          # "smell_warning" is defined in BaseDetector and should be used by you
+          # to construct smell warnings
+          smell_warning(
+            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
+            # parameters below - if you do not interpolate anything you
+            # can omit this
+            parameters: { })
+          end
+        end
+      end
+
+      private
+
+      # Here goes everything you need for finding smells.
+    end
+  end
+end
+```
+
+For your detector to be properly loaded you need to require it in `lib/reek/smell_detectors.rb` as well.
+
+### defaults.reek.yml
+
+After you ran
+
+```
+bundle exec rake
+```
+
+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.
+
+### Documentation
+
+* Above every `SmellDetector::sniff` method it should be documented what the expected AST is
+* Every detector should have a separate documentation page in /docs. You can
+  take any arbitrary existing smell detector documentation page as template (since
+  they all have the same structure already)
+* The detector should be listed under [Code Smells](docs/Code-Smells.md)
+* Depending on what your detector does it might make sense to add it to other doc pages as
+  well e.g. [Simulated Polymorphism](docs/Simulated-Polymorphism.md)
+
+### Rspec examples
+
+All smell detector specs start out with 2 generic examples like below - the second one
+only if it makes sense.
+Here's what it looks like for `UncommunicativeVariableName`:
+
+```ruby
+it 'reports the right values' do
+  src = <<-RUBY
+    def alfa
+      bravo = 5
+    end
+  RUBY
+
+  expect(src).to reek_of(:UncommunicativeVariableName,
+                         lines:   [2],
+                         context: 'alfa',
+                         message: "has the variable name 'bravo'",
+                         source:  'string',
+                         name:    'bravo')
+end
+
+it 'does count all occurrences' do
+  src = <<-RUBY
+    def alfa
+      bravo = 3
+      charlie = 7
+    end
+  RUBY
+
+  expect(src).to reek_of(:UncommunicativeVariableName,
+                         lines: [2],
+                         name:  'bravo')
+  expect(src).to reek_of(:UncommunicativeVariableName,
+                         lines: [3],
+                         name:  'charlie')
+end
+```
+
+The following examples should then cover the detector specific features.
+
+### Schema validation
+
+We make use of [dry-schema](https://github.com/dry-rb/dry-schema) to validate the
+the reek configuration file (usually named `.reek.yml` in the root of a project).
+The validation will warn reek users of missing or incorrectly defined configuration.
+
+If you add or modify a detector you will need to make sure that you update the 
+[schema](lib/reek/configuration/schema.rb) file. For help with the schema syntax
+you can refer to the [dry-schema documentation](https://dry-rb.org/gems/dry-schema).
+You can also take a look at the existing schema rules for they all look fairly
+similar.
+
+### Cucumber features
+
+We are trying to write as few Cucumber features as possible.
+Normally, there should be no need to write a new feature for a new smell detector.
+If you feel like this is necessary in this case, please discuss this with us via
+github issue or in your work-in-progress pull request before doing anything.

data/data/reek_docs/How-reek-works-internally.md

@@ -0,0 +1,114 @@
+# How Reek works internally
+
+
+## The big picture
+
+```
+["class C; end" | reek]            [reek lib/*.rb]                             [expect(files).not_to reek_of(:LargeClass)]
+             \                            |                                                          |
+              \                           |                                                          |
+               \                          |                                                          |
+                \             creates a   |                                                          |
+                 \                        |                                                          |
+                  \                       |                                                          |
+                   \                      |                                                          |
+                    \                     |                                                          |
+                     \---------- Application (cli/application.rb) +                                  |
+                                    Options (cli/options)                                            |
+                                          |                                                          |
+                                          |                                                          |
+                                          |                                                          |
+                                          |                                                          |
+                              creates a   |                                                          |
+                                          |                                                          |
+                                          |                                                          |
+                                          |                                                          |
+                                          |                                                          |
+                                ReekCommand (cli/reek_command)                                       |
+                                * uses a reporter (report/report)                                    |
+                                * uses a SourceLocator (source/source_locator)                       |
+                                /         |         \                                                |
+                               /          |          \                                               |
+                              /           |           \                                              |
+                        Source          Source      Source (source/source_code)                      |
+                          |               |            |                                             |
+                          |               |            |                                             |
+                          |               |            |                                             |
+                      Examiner            |         Examiner                                         |
+                                          |                                                          |
+                                          |                                                          |
+                                      Examiner (core/examiner)  --------------------------------------
+                                  * generates the AST out of the given source
+                                  * adorns the generated AST via a TreeDresser (core/tree_dresser)
+                                  * initializes a DetectorRepository with all relevant smells (smells/detector_repository)
+                                  * builds a tree of Contexts using ContextBuilder
+                                  * tells the DetectorRepository above to run each of its smell detectors above on each of the contexts
+                                  /       |       \
+                                 /        |        \
+                                /         |         \
+                    UtilityFunction   FeatureEnvy   TooManyMethods
+                                \         |         /
+                                 \        |        /
+                                  \       |       /
+                                   DetectorRepository
+                                          |
+                                          |
+                                          |
+                                    Application output
+
+## A closer look at how an Examiner works
+
+The core foundation of Reek and its API is the Examiner.
+As you can see above, the Examiner is run for every source it gets passed and then runs the configured SmellDetectors.
+The overall workflow is like this:
+
+        Examiner
+            |
+            |
+            |
+        Initialize DetectorRepository only with eligible SmellDetectors
+            |
+            |
+            |
+    Generate the AST out of the given source using SourceCode#syntax_tree, which works like this:
+
+      - We generate a "rough" AST using the "parser" gem
+      - We then obtain the comments from the source code separately
+      - We pass this unprocessed AST and the comment_map to TreeDresser#dress which
+        returns an instance of Reek::AST::SexpNode with type-dependent SexpExtensions mixed in.
+
+    An example should make this more palpable.
+    Given:
+
+      class C
+        def m
+          puts 'nada'
+        end
+      end
+
+    The AST generated by the parser gem (consisting of Parser::AST::Node) looks like this:
+
+       (class
+         (const nil :C)
+          nil
+         (def :m
+           (args)
+           (send nil :puts
+             (str "nada"))))
+
+    TreeDresser#dress would transform this into a very similar tree, but this time not consisting
+    of Parser::AST::Node but of Reek::AST::SexpNode and with node-dependent SexpExtensions
+    mixed in (noted in []):
+
+       (class                 [AST::SexpExtensions::ClassNode, AST::SexpExtensions::ModuleNode]
+         (const nil :C)       [AST::SexpExtensions::ConstNode]
+          nil
+         (def :m              [AST::SexpExtensions::DefNode, AST::SexpExtensions::MethodNodeBase]
+           (args)             [AST::SexpExtensions::ArgsNode]
+           (send nil :puts    [AST::SexpExtensions::SendNode]
+             (str "nada"))))
+            |
+            |
+            |
+      A ContextBuilder then traverses this now adorned tree again and
+      runs all SmellDetectors from the DetectorRepository above