excellent 1.7.2 → 2.0.0

data/History.txt

@@ -1,9 +1,18 @@
 =======
+= 2.0.0
+
+* now supporting config file .excellent.yml in current working directory to configure which specs to run/ not to run with thresholds, patterns etc.
+* predefined globals will not be reported anymore ($!, $@, $&, $`, $', $+, $1, $2.., $~, $=, $/, $\, $,, $;, $., $<, $>, $_, $0, $*, $$, $?, $:, $", $DEBUG, $FILENAME, $LOAD_PATH, $stdin, $stdout, $stderr, $VERBOSE, option variables, $-0, $-a, $-d, $-F, $-i, $-I, $-l, $-p, $-v)
+* enabled previously disable checks again: AbcMetricMethodCheck, ControlCouplingCheck, CyclomaticComplexityBlockCheck, CyclomaticComplexityMethodCheck, ForLoopCheck, FlogBlockCheck, FlogClassCheck, FlogMethodCheck
+* testing now uses Rspec 2
+* internal cleanups/ simplifications
+
 = 1.7.2
 
 * fixed Simplabs::Excellent::Checks::Rails::CustomInitializeMethodCheck
 * fixed Simplabs::Excellent::Checks::MethodNameCheck so it allows method names that exist in Ruby itself
 * fixed Simplabs::Excellent::Checks::GlobalVariableCheck so it doesn't report false positives for rescue bodies
+* made the parser more forgiving/stable in some situations
 
 = 1.7.1
 

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008-2009 Marco Otte-Witte
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,123 @@
+Excellent
+=========
+
+[![Build Status](https://travis-ci.org/simplabs/excellent.png)](https://travis-ci.org/simplabs/excellent)
+
+Excellent **finds the nasty lines in your code**. It implements a comprehensive set of checks for possibly
+buggy parts of your app that would **otherwise make it into your repo and eventually to the production server**.
+
+See the API documentation at [http://docs.github.com/simplabs/excellent](http://docs.github.com/simplabs/excellent)
+and the Wiki at [http://wiki.github.com/simplabs/excellent](http://wiki.github.com/simplabs/excellent).
+
+Installation
+------------
+
+Simply install with Ruby Gems:
+
+```bash
+gem install excellent
+```
+
+Example
+-------
+
+Assume you have the following class definition,
+
+```ruby
+class ShoppingBasket < ActiveRecord::Base
+
+  def initialize(items = [])
+    self.items = items
+  end
+
+end
+````
+
+then Excellent will report the problems in this piece of code:
+
+```bash
+$ excellent shopping_basket.rb
+
+  Excellent result:
+
+  test.rb
+    * Line   1: ShoppingBasket does not validate any attributes.
+    * Line   1: ShoppingBasket defines initialize method.
+    * Line   1: ShoppingBasket does not specify attr_accessible.
+
+  Found 3 warnings.
+```
+
+To analyse all the models in your Rails application, just do
+
+```bash
+excellent app/models
+```
+
+in your `RAILS_ROOT`. You can also invoke analysation through the `Simplabs::Excellent::Runner` class.
+Excellent can also produce HTML output. To get a formatted HTML report, just specify `html:<filename>`:
+
+```bash
+excellent -o out.html app/models
+```
+
+You can also use Excellent in a Rake task:
+
+```ruby
+require 'simplabs/excellent/rake'
+
+Simplabs::Excellent::Rake::ExcellentTask.new(:excellent) do |t|
+  t.html  = 'doc/excellent.html' # optional, if you don't specify html, output will be written to $stdout
+  t.paths = %w(app lib)
+end
+```
+
+Configuration
+-------------
+
+You can configure which checks to run and which thresholds etc. to use. Simply place a `.excellent.yml` in the
+root directory of you project (the directory that you will be starting excellent from). You can enable/disable
+by using the check name as hash key and specifying a truthy/falsy value:
+
+```yaml
+AbcMetricMethodCheck: true
+AssignmentInConditionalCheck: false
+```
+
+By default all checks are enabled so you would usually only switch off certain checks you're not interested in.
+Some checks also take cofngigurations like thresholds, patterns etc. You can configure those by simply defining
+nested hashes in the YAML:
+
+```yaml
+ClassLineCountCheck:
+  threshold: 500
+MethodNameCheck:
+  pattern: '^[a-z].*'
+```
+
+This would for example only report classes with more than 500 lines and require that all method names start
+with a lower case letter.
+
+You can get a list of the enabled checks and their configurations by running:
+
+```bash
+excellent --checks
+```
+
+Static analysis
+---------------
+
+A few words regarding static code analysis: Static code analysis tools like Excellent can never really
+understand the code. They just search for patterns that *might* inidicate problematic code. The word **might**
+really has to be stressed here since static analysis will usually return a reasonable number of false
+positives. For example, there might be pretty good reasons for empty +rescue+ blocks that suppress all
+errors (Excellent itself does it). So, don't try and code with the aim of passing Excellent with zero warnings.
+That will most likely make your code a mess. Instead use Excellent as a helper to find **potentially**
+problematic code early.
+
+Author
+------
+
+Copyright (c) 2008-2013 Marco Otte-Witte ([http://simplabs.com](http://simplabs.com)), released under the MIT license.
+
+Excellent was inspired by roodi ([https://github.com/martinjandrews/roodi](https://github.com/martinjandrews/roodi)), reek ([https://github.com/troessner/reek](https://github.com/troessner/reek)) and flog ([https://github.com/seattlerb/flog](https://github.com/seattlerb/flog)).

data/bin/excellent

@@ -8,9 +8,12 @@ options = {}
 
 optparse = OptionParser.new do |opt|
   opt.banner = 'Usage: excellent [OPTIONS] <PATH1> [<PATH2> ...]'
-  opt.on('--output', '-o [FILE]', 'Write HTML output to [FILE].') do |target|
+  opt.on('--output', '-o [FILE]', 'Write HTML output to [FILE]') do |target|
     options[:output] = target
   end
+  opt.on('--checks', 'Show a list of the enabled checks and their configuraton values') do |target|
+    options[:print_checks] = true
+  end
   opt.on_tail('--help', '-h', 'Help') do
     puts optparse
     exit
@@ -24,27 +27,61 @@ end
 optparse.parse!
 
 target = options[:output]
-paths  = ARGV.dup
-
-if paths.empty?
-  puts "\n  You must specify one or more directories to analyse, e.g.:\n"
-  puts "\n    excellent lib/\n\n"
-  exit 1
-end
-
 if target
   begin
     fileio = File.open(target, 'w+')
     formatter = Simplabs::Excellent::Formatters::Html.new(fileio)
   rescue Errno::ENOENT
-    puts "\n  #{target} cannot be opened for writing. Specify a file name like so:\n"
-    puts "\n    excellent -o excellent.html lib/\n\n"
+    puts "\n  **#{target} cannot be opened for writing. Specify a file name like so:\n"
+    puts "\n      excellent -o excellent.html lib/\n\n"
   end
 else
   formatter = Simplabs::Excellent::Formatters::Text.new
 end
 
-excellent = Simplabs::Excellent::Runner.new
+custom_config = {}
+config_file   = File.join(Dir.pwd, '.excellent.yml')
+if File.exists?(config_file)
+  require 'yaml'
+  begin
+    custom_config = YAML.load(File.open(config_file)) || {}
+    config_valid  = custom_config.is_a?(Hash) && custom_config.all? do |key, value|
+      key.is_a?(String) || key.is_a?(Symbol)
+    end
+  rescue Exception
+    config_valid = false
+  end
+  unless config_valid
+    puts "\n  ** The configuration in #{config_file} is not valid!\n\n"
+    puts "     Please make sure you specify a hash with check names as keys and hashes or truthy/falsy values as hash values, e.g.:\n\n"
+    puts "       AbcMetricMethodCheck:"
+    puts "         false"
+    puts "       ClassLineCountCheck:"
+    puts "         threshold: 10"
+    puts "\n\n"
+    exit 1
+  end
+end
+
+excellent = Simplabs::Excellent::Runner.new(custom_config)
+
+if options[:print_checks]
+  puts "\n  Configured Checks\n\n"
+  excellent.checks.each do |check|
+    puts "    #{check.class.name.gsub('Simplabs::Excellent::Checks::', '')}"
+    check.options.each do |key, value|
+      puts "      #{key}: #{value}"
+    end
+  end
+  exit 0
+end
+
+paths  = ARGV.dup
+if paths.empty?
+  puts "\n  **You must specify one or more directories to analyse, e.g.:\n"
+  puts "\n    excellent lib/\n\n"
+  exit 1
+end
 
 begin
   excellent.check_paths(paths, formatter)

data/lib/simplabs/excellent.rb

@@ -2,14 +2,14 @@ require 'simplabs/excellent/checks'
 require 'simplabs/excellent/parsing'
 require 'simplabs/excellent/formatters'
 require 'simplabs/excellent/runner'
-require 'rubygems'
 require 'sexp'
+require 'hashr'
 
 module Simplabs #:nodoc:
 
   module Excellent #:nodoc:
 
-    VERSION = '1.7.2'
+    VERSION = '2.0.0'
 
   end
 

data/lib/simplabs/excellent/checks.rb

@@ -14,7 +14,7 @@ require 'simplabs/excellent/checks/assignment_in_conditional_check'
 require 'simplabs/excellent/checks/case_missing_else_check'
 require 'simplabs/excellent/checks/class_line_count_check'
 require 'simplabs/excellent/checks/class_name_check'
-require 'simplabs/excellent/checks/singleton_variable_check'
+require 'simplabs/excellent/checks/class_variable_check'
 require 'simplabs/excellent/checks/global_variable_check'
 require 'simplabs/excellent/checks/control_coupling_check'
 require 'simplabs/excellent/checks/cyclomatic_complexity_block_check'

data/lib/simplabs/excellent/checks/abc_metric_method_check.rb

@@ -23,7 +23,7 @@ module Simplabs
         DEFAULT_THRESHOLD = 10
 
         def initialize(options = {}) #:nodoc:
-          super()
+          super
           @threshold            = options[:threshold] || DEFAULT_THRESHOLD
           @interesting_contexts = [Parsing::MethodContext, Parsing::SingletonMethodContext]
         end

data/lib/simplabs/excellent/checks/assignment_in_conditional_check.rb

@@ -21,7 +21,7 @@ module Simplabs
       class AssignmentInConditionalCheck < Base
 
         def initialize(options = {}) #:nodoc:
-          super()
+          super
           @interesting_contexts = [Parsing::IfContext, Parsing::WhileContext, Parsing::UntilContext]
           @interesting_files    = [/\.rb$/, /\.erb$/]
         end

data/lib/simplabs/excellent/checks/base.rb

@@ -10,7 +10,9 @@ module Simplabs
       # will invoke the +evaluate_context+ method of all checks that specify the context as one if their +interesting_contexts+.
       class Base
 
-        attr_reader :warnings
+        attr_reader :warnings #:nodoc:
+
+        attr_reader :options #:nodoc:
 
         # An array of contexts that are interesting for the check. These contexts are based on symbols as returned by RubyParser (see
         # http://parsetree.rubyforge.org/ruby_parser/) and add some additional data,
@@ -23,12 +25,14 @@ module Simplabs
         # Defaults to /\.rb$/. If you do not specify anything else in custom checks, only *.rb files will be processed
         attr_reader :interesting_files
 
-        def initialize #:nodoc:
-          @warnings          = []
-          @interesting_files = [/\.rb$/]
+        def initialize(options = {}) #:nodoc:
+          @options              = options
+          @interesting_contexts = []
+          @warnings             = []
+          @interesting_files    = [/\.rb$/]
         end
 
-        # This method is called whenever Excellent processes a context that the check specified as one of the contexts it is interested in (see 
+        # This method is called whenever Excellent processes a context that the check specified as one of the contexts it is interested in (see
         # interesting_contexts).
         #
         # ==== Parameters
@@ -47,14 +51,13 @@ module Simplabs
         # * <tt>info</tt> - The information hash that contains more info on the finding.
         # * <tt>offset</tt> - The line offset that is added to the context's line property.
         def add_warning(context, message, info = {}, offset = 0)
-          klass = self.class
-          @warnings << Simplabs::Excellent::Warning.new(klass, message, context.file, context.line + offset, info)
+          @warnings << Simplabs::Excellent::Warning.new(message, context.file, context.line + offset, info)
         end
-  
+
         def warnings_for(filename) #:nodoc:
           warnings.select { |warning| warning.filename == filename }
         end
-  
+
       end
 
     end

data/lib/simplabs/excellent/checks/case_missing_else_check.rb

@@ -15,7 +15,7 @@ module Simplabs
       # * +case+ statements
       class CaseMissingElseCheck < Base
 
-        def initialize #:nodoc:
+        def initialize(options = {}) #:nodoc:
           super
           @interesting_contexts = [Parsing::CaseContext]
           @interesting_files    = [/\.rb$/, /\.erb$/]

data/lib/simplabs/excellent/checks/class_line_count_check.rb

@@ -14,11 +14,11 @@ module Simplabs
       # * classes
       class ClassLineCountCheck < LineCountCheck
 
-        DEFAULT_THRESHOLD = 400
+        DEFAULT_THRESHOLD = 300
 
         def initialize(options = {}) #:nodoc:
-          threshold = options[:threshold] || DEFAULT_THRESHOLD
-          super([Parsing::ClassContext], threshold)
+          options[:threshold] ||= DEFAULT_THRESHOLD
+          super([Parsing::ClassContext], options)
         end
 
         def evaluate(context)

data/lib/simplabs/excellent/checks/class_name_check.rb

@@ -16,13 +16,13 @@ module Simplabs
       # * classes
       class ClassNameCheck < NameCheck
 
-        DEFAULT_PATTERN = /^[A-Z]{1}[a-zA-Z0-9]*$/
-      
+        DEFAULT_PATTERN = '^[A-Z]{1}[a-zA-Z0-9]*$'
+
         def initialize(options = {}) #:nodoc:
-          pattern = options[:pattern] || DEFAULT_PATTERN
-          super([Parsing::ClassContext], pattern)
+          options[:pattern] ||= DEFAULT_PATTERN
+          super([Parsing::ClassContext], options)
         end
-      
+
         protected
 
           def warning_args(context) #:nodoc:

data/lib/simplabs/excellent/checks/{singleton_variable_check.rb → class_variable_check.rb}

@@ -12,16 +12,16 @@ module Simplabs
       # ==== Applies to
       #
       # * class variables
-      class SingletonVariableCheck < Base
+      class ClassVariableCheck < Base
 
-        def initialize #:nodoc:
+        def initialize(options = {}) #:nodoc:
           super
           @interesting_contexts = [Parsing::CvarContext]
           @interesting_files = [/\.rb$/, /\.erb$/]
         end
 
         def evaluate(context) #:nodoc:
-          add_warning(context, 'Singleton variable {{variable}} used.', { :variable => context.full_name })
+          add_warning(context, 'Class variable {{variable}} used.', { :variable => context.full_name })
         end
 
       end

data/lib/simplabs/excellent/checks/control_coupling_check.rb

@@ -15,7 +15,7 @@ module Simplabs
       # * methods
       class ControlCouplingCheck < Base
 
-        def initialize #:nodoc:
+        def initialize(options = {}) #:nodoc:
           super
           @interesting_contexts = [Parsing::IfContext, Parsing::CaseContext]
         end

data/lib/simplabs/excellent/checks/cyclomatic_complexity_block_check.rb

@@ -27,12 +27,12 @@ module Simplabs
       class CyclomaticComplexityBlockCheck < CyclomaticComplexityCheck
 
         DEFAULT_THRESHOLD = 4
-      
+
         def initialize(options = {}) #:nodoc:
-          threshold = options[:threshold] || DEFAULT_THRESHOLD
-          super([Parsing::BlockContext], threshold)
+          options[:threshold] ||= DEFAULT_THRESHOLD
+          super([Parsing::BlockContext], options)
         end
-      
+
         def evaluate(context) #:nodoc:
           unless context.cc_score <= @threshold
             add_warning(context, '{{block}} has cyclomatic complexity of {{score}}.', { :block => context.full_name, :score => context.cc_score })

data/lib/simplabs/excellent/checks/cyclomatic_complexity_check.rb

@@ -8,10 +8,10 @@ module Simplabs
 
       class CyclomaticComplexityCheck < Base #:nodoc:
 
-        def initialize(interesting_contexts, threshold)
-          super()
+        def initialize(interesting_contexts, options = {}) #:nodoc:
+          super(options)
           @interesting_contexts = interesting_contexts
-          @threshold            = threshold
+          @threshold            = options[:threshold].to_i
         end
 
       end