reek 2.2.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 988f551b421341be717b93689070ad4d8b809a2a
-  data.tar.gz: 2089735509323d24ea39425e5aa3a67ba888cb40
+  metadata.gz: da371c20978d5a436025bc2ecddc2df4582a9c7e
+  data.tar.gz: 8aa3729d6814cba34e69ff9e1696ce93450221c6
 SHA512:
-  metadata.gz: 38f11b564b3ae5f11d53849ece35b2ea544f83c4ced89e4e344a8a4b7a2d76470f614fd51890f2379faeac35860cc01fca62c643c8a864786ac15a3640c8aa16
-  data.tar.gz: c24c9b966287c29db29073c5aad19e4890d1949d9d49c0d38478d4ed48f45818d4665b302704a98a58867f99156ee0865cccff71ebb18fbda90bd34eeca9e2c1
+  metadata.gz: d15340c5aa637820c280d28008579ecc97f9de7a56bf74e47f6f217a9f593d3a1416dfa6757b4beb3900032c505eed91aa8fa21de94374ac1e2d1537706cbabb
+  data.tar.gz: c49a1ae86f1265e493f6e5eff700e2d02c2849358a49db20d87d9c52498138da0ca38fd7bd83cb90d0c16cb7b19789aa43422b052910b145ac611d9421bc6bf8

data/.rubocop.yml

@@ -7,7 +7,7 @@ AllCops:
 # FIXME: Make the class shorter
 Metrics/ClassLength:
   Exclude:
-    - lib/reek/core/tree_walker.rb
+    - lib/reek/tree_walker.rb
     - lib/reek/cli/options.rb
 
 # FIXME: Lower the method length by fixing the biggest offenders

data/.travis.yml

@@ -2,19 +2,24 @@ sudo: false
 cache: bundler
 language: ruby
 bundler_args: --without local_development
-script: bundle exec rake
+script:
+- bundle exec rake
+- bundle exec ataru check
 rvm:
-  - 1.9.3
   - 2.0.0
   - 2.1
   - 2.2
-  - jruby-19mode
   - rbx-2
   - ruby-head
-  - jruby-head
 matrix:
+  include:
+    - rvm: jruby-19mode
+      env: JRUBY_OPTS='--server -Xcompile.invokedynamic=false'
+    - rvm: jruby-head
+      env: JRUBY_OPTS='--server -Xcompile.invokedynamic=false'
   allow_failures:
     - rvm: jruby-head
+      env: JRUBY_OPTS='--server -Xcompile.invokedynamic=false'
     - rvm: ruby-head
   fast_finish: true
 notifications:

data/CHANGELOG

@@ -1,3 +1,11 @@
+== 3.0.0
+
+* (troessner) Make directories excludable via configuration.
+* (mvz) Define and document public API
+* (troessner) Recognize methods defined with class << self syntax as singleton methods.
+* (troessner)  Use ruby22 instead of ruby21 for parsing.
+* (nTraum) Drop support for Ruby 1.9
+
 == 2.2.1
 
 * (mvz) Support methods using array decomposition arguments

data/Gemfile

@@ -5,10 +5,12 @@ gemspec
 
 group :local_development do
   gem 'pry'
+  gem 'yard', '~> 0.8.7'
+
   platforms :mri do
-    if RUBY_VERSION >= '2.0.0'
-      gem 'byebug'
-      gem 'pry-byebug'
-    end
+    gem 'pry-byebug'
+    gem 'pry-stack_explorer'
+
+    gem 'redcarpet', '~> 3.3.1'
   end
 end

data/README.md

@@ -173,8 +173,14 @@ NestedIterators:
 DataClump:
   max_copies: 3
   min_clump_size: 3
+
+exclude_paths:
+  - app/views
+  - app/controllers
 ```
 
+Additionally to the smell configuration you can exclude whole directories from scans using `exclude_paths` as you can see at the end of the configuration above.
+
 ### Source code comments
 
 `reek` is not the police. In case you need to suppress a smell

data/docs/API.md

@@ -1,6 +1,4 @@
-# API
-
-## Using `reek` inside your Ruby application
+# Using `reek` inside your Ruby application
 
 `reek` can be used inside another Ruby project.
 
@@ -8,37 +6,41 @@
 gem install reek
 ```
 
+## Using a reporter
+
 You can use reek inside your Ruby file `check_dirty.rb`
 
 ```ruby
 require 'reek'
-require 'reek/source/source_code'
-require 'reek/cli/report/report'
-require 'reek/core/examiner'
-
-source =<<END
-class Dirty
-  # This method smells of :reek:NestedIterators but ignores them
-  def awful(x, y, offset = 0, log = false)
-    puts @screen.title
-    @screen = widgets.map { |w| w.each { |key| key += 3 * x } }
-    puts @screen.contents
-    fail
+
+source = <<-END
+  class Dirty
+    # This method smells of :reek:NestedIterators but ignores them
+    def awful(x, y, offset = 0, log = false)
+      puts @screen.title
+      @screen = widgets.map { |w| w.each { |key| key += 3 * x } }
+      puts @screen.contents
+      fail
+    end
   end
-end
 END
 
-source_code = Reek::Source::SourceCode.from(source)
-reporter = Reek::CLI::Report::TextReport.new
-reporter.add_examiner Reek::Core::Examiner.new(source_code)
-puts reporter.show
+reporter = Reek::Report::TextReport.new
+examiner = Reek::Examiner.new(source)
+reporter.add_examiner examiner
+reporter.show
 ```
 
 This will show the list of errors in variable `source`.
 
-`reek` can take `source` as `String`, `File` or `IO`.
+`Reek::Examiner.new` can take `source` as `String`, `File` or `IO`.
+
+```
+# Examine a file object
+reporter.add_examiner Reek::Examiner.new(File.new('dirty.rb'))
+```
 
-Also, besides normal text output, `reek` can also generate output in YAML,
+Also, besides normal text output, `reek` can generate output in YAML,
 JSON, HTML and XML by using the following Report types:
 
 ```
@@ -48,3 +50,30 @@ JSONReport
 HTMLReport
 XMLReport
 ```
+
+## Accessing the smell warnings directly
+
+You can also access the smells detected by an examiner directly:
+
+```ruby
+require 'reek'
+
+source = <<-END
+  class Dirty
+    # This method smells of :reek:NestedIterators but ignores them
+    def awful(x, y, offset = 0, log = false)
+      puts @screen.title
+      @screen = widgets.map { |w| w.each { |key| key += 3 * x } }
+      puts @screen.contents
+      fail
+    end
+  end
+END
+
+examiner = Reek::Examiner.new(source)
+examiner.smells.each do |smell|
+  puts smell.message
+end
+```
+
+`Examiner#smells` returns a list of `SmellWarning` objects.

data/docs/Configuration-Files.md

@@ -14,7 +14,7 @@ The order in which `reek` tries to find such a configuration file is exactly lik
 
 As soon as `reek` detects a configuration file it stops searching immediately, meaning that from `reek`'s point of view there exists one configuration file and one configuration only regardless of how many ".reek" files you might have on your filesystem.
 
-## Configuration options
+## Configuration options for smells
 
 The first thing you probably want to check out are the [Basic Smell Options](Basic-Smell-Options.md) which are supported by every smell type.
 Certain smell types offer a configuration that goes beyond that of the basic smell options - for instance [Data Clump](Data-Clump.md).
@@ -36,3 +36,14 @@ DataClump:
   max_copies: 3
   min_clump_size: 3
 ```
+
+## Excluding directories from scans
+
+You can exclude whole directories from scans using `exclude_paths` in your configuration file:
+
+```yaml
+---
+exclude_paths:
+  - app/views
+  - app/controllers
+```

data/docs/Feature-Envy.md

@@ -2,28 +2,48 @@
 
 ## 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_ 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.
 
-A simple example would be the following method, which "belongs" on the Item class and not on the Cart class:
+_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 Cart
-  def price
-    @item.price + @item.tax
+class Warehouse
+  def sale_price(item)
+    (item.price - item.rebate) * @vat
   end
 end
 ```
 
-`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.
+would report:
 
-`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.
+```Bash
+Warehouse#total_price refers to item more than self (FeatureEnvy)
+```
 
-`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.
+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.
+_Feature Envy_ reports any method that refers to self less often than it refers to (ie. send messages to) some other object.
+
+## 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).
+_Feature Envy_ supports the [Basic Smell Options](Basic-Smell-Options.md).

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

@@ -1,44 +1,114 @@
 # How reek works internally
 
-**Using reek via bin/reek:**
+
+## The big picture
 
 ```
-            [bin/reek]
-                |
-                |
-                |
-          Application (cli/application.rb) +
-          Options (cli/options)
-                |
-                |
-                |
-      ReekCommand (cli/reek_command)
-      with Reporter (cli/report/report)
-          /     |    \
-         /      |     \
-        /       |      \
-    Source   Source   Source (source/source_code)
-    |           |          |
-    |           |          |
-    |           |          |
- Examiner   Examiner  Examiner (examiner)
-                |
-                |
-                |
-    Examiner sets up a:
-      - SourceRepository (source/source_repository)
-      - a WarningCollector (core/warning_collector)
-
-    The Examiner then goes through each source:
-      - Initializing a SmellRepository (core/smell_repository)
-      - getting the AST from the source
-      - applying a TreeWalker(core/tree_walker) to process this syntax tree given the SmellRepository
-      - finally have that SmellRepository reporting back on the WarningCollector mentioned above
-                |
-                |
-                |
-    In the last step, the reporter from the ReekCommand:
-      - gathers all the warnings from the collectors of all Examiners (as you can see here https://github.com/troessner/reek/blob/master/lib/reek/cli/report/report.rb#L30)
-      - outputs them with whatever output format we have chose via the cli options
-```
+["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 SmellRepository with all relevant smells (smells/smell_repository)
+                                  * initializes a WarningCollector (cli/warning_collector)
+                                  * runs all corresponding smell detectors via a Treewalker (core/tree_walker) for the SmellRepository above
+                                  /       |       \
+                                 /        |        \
+                                /         |         \
+                    UtilityFunction   FeatureEnvy   TooManyMethods
+                                \         |         /
+                                 \        |        /
+                                  \       |       /
+                                   WarningCollector
+                                          |
+                                          |
+                                          |
+                                    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 SmellRepository only with eligible smells
+            |
+            |
+            |
+    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 TreeWalker then traverses this now adorned tree again and
+      runs all SmellDetectors from the SmellRepository above

data/docs/RSpec-matchers.md

@@ -37,7 +37,7 @@ end
 Running this via
 
 ```
-rspec reek-integration-spec.rb 
+rspec reek-integration-spec.rb
 ```
 
 would give you:
@@ -65,7 +65,8 @@ rspec ./reek-integration-spec.rb:6 # Reek Integration works with reek
 
 ### `reek`
 
-A very generic matcher that basically just tells you if something reeks, but not after what exactly.
+A very generic matcher that basically just tells you if something reeks, but
+not after what exactly.
 See the "Quickstart" example from above.
 
 ### `reek_of`
@@ -78,27 +79,29 @@ Remember that this includes our "smell types" as well. So it could be the
 in reek but it could also be "Duplication" which is a "smell categgory".
 
 In theory you could pass many different types of input here:
-  - :UtilityFunction
-  - "UtilityFunction"
-  - UtilityFunction (this works in our specs because we tend to do "include Reek:Smells")
-  - Reek::Smells::UtilityFunction (the right way if you really want to pass a class)
-  - "Duplication" or :Duplication which is an abstract "smell category"
-
-It is recommended to pass this as a symbol like :UtilityFunction. However we don't
-enforce this.
-
-Additionally you can be more specific and pass in "smell_details" you
-want to check for as well e.g. "name" or "count" (see the examples below).
-The parameters you can check for are depending on the smell you are checking for.
-For instance "count" doesn't make sense everywhere whereas "name" does in most cases.
-If you pass in a parameter that doesn't exist (e.g. you make a typo like "namme") reek will
-raise an ArgumentError to give you a hint that you passed something that doesn't make
-much sense.
+- `:UtilityFunction`
+- `"UtilityFunction"`
+- `UtilityFunction` (this works in our specs because we tend to do "include
+  Reek:Smells")
+- `Reek::Smells::UtilityFunction` (the right way if you really want to pass a
+  class)
+- `"Duplication"` or `:Duplication` which is an abstract "smell category"
+
+It is recommended to pass this as a symbol like `:UtilityFunction`. However we
+don't enforce this.
+
+Additionally you can be more specific and pass in "smell_details" you want to
+check for as well e.g. "name" or "count" (see the examples below). The
+parameters you can check for are depending on the smell you are checking for.
+For instance "count" doesn't make sense everywhere whereas "name" does in most
+cases. If you pass in a parameter that doesn't exist (e.g. you make a typo like
+"namme") reek will raise an ArgumentError to give you a hint that you passed
+something that doesn't make much sense.
 
 So in a nutshell `reek_of` takes the following two arguments:
 
-- smell_category - The "smell category" or "smell_type" we check for.
-- smells_details - A hash containing "smell warning" parameters
+- `smell_category` - The "smell category" or "smell_type" we check for.
+- `smells_details` - A hash containing "smell warning" parameters
 
 **Examples**
 
@@ -128,6 +131,7 @@ See the documentaton for `reek_of`.
 
 **Notable differences to reek_of:**
 
-1.) `reek_of` doesn't mind if there are other smells of a different category. "reek_only_of" will fail in that case.
+1. `reek_of` doesn't mind if there are other smells of a different category.
+   "reek_only_of" will fail in that case.
 
-2.) `reek_only_of` doesn't support the additional smell_details hash.
+2. `reek_only_of` doesn't support the additional smell_details hash.