simplabs-excellent 1.0.1 → 1.2.1

data/History.txt

@@ -1,3 +1,22 @@
+= 1.2.1
+
+* renamed Error to Warning
+* added documentation
+
+= 1.2.0
+
+* cleanup
+* added 2 Rails specific checks, AttrAccessibleCheck and AttrProtectedCheck
+
+= 1.1.0
+
+* completely restructured, made everything running in the flow of the SexpProcessor
+* added most tests from reek (except for UtilityFunction and FeatureEnvy)
+
+= 1.0.1
+
+* fixed some errors
+
 = 1.0.0
 
 * this is basically just a custom version of roodi, converted to ruby_parser to be 1.9 safe

data/README.rdoc

@@ -0,0 +1,34 @@
+= Excellent
+
+Excellent detects commonly regarded bad code snippets like empty +rescue+ blocks etc. It combines roodi (http://github.com/martinjandrews/roodi), most checks of reek (http://github.com/kevinrutherford/reek), flog (http://github.com/seattlerb/flog) and also adds some Rails specific checks.
+
+See the API documentation at http://docs.github.com/simplabs/excellent and the WIKI at http://wiki.github.com/simplabs/excellent.
+
+== Installation
+
+Simply install with Ruby Gems:
+
+  gem sources -a http://gems.github.com
+  sudo gem install simplabs-excellent
+
+== Example
+
+To analyse all the models in your Rails application, just do
+
+  excellent app/models
+
+in your <tt>RAILS_ROOT</tt>. You can also invoke analysation through the Simplabs::Excellent::Runner class.
+
+== 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 *possibly* problematic code early.
+
+== Contribute
+
+If you want to contribute, just fork the repo. Also I would appretiate suggestions for more checks (especially Rails specific checks) - simply open a new issue: http://github.com/simplabs/excellent/issues.
+
+== Author
+
+Copyright (c) 2008-2009 Marco Otte-Witte (http://simplabs.com), released under the MIT license.
+
+Excellent was inspired by and is in parts based on roodi (http://github.com/martinjandrews/roodi), reek (http://github.com/kevinrutherford/reek) and flog (http://github.com/seattlerb/flog).

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 1
-:minor: 0
+:minor: 2
 :patch: 1

data/bin/excellent

@@ -5,16 +5,31 @@ $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + "/../lib"))
 require 'simplabs/excellent'
 require 'pathname'
 
-excellent = Simplabs::Excellent::Core::ParseTreeRunner.new
+excellent = Simplabs::Excellent::Runner.new
+
+if ARGV.empty?
+  puts "\n  You must specify one or more directories to analyse, e.g.:\n"
+  puts "\n    excellent app/\n\n"
+  exit 1
+end
 
 ARGV.each do |arg|
-  Dir.glob(arg).each { |file| excellent.check_file(file) }
+  if File.file?(arg)
+    excellent.check_file(arg)
+  elsif File.directory?(arg)
+    Dir.glob("#{arg}/**/*.rb").each { |file| excellent.check_file(file) }
+  else
+    puts "\n** Excellent cannot find '#{arg}'\n\n"
+    exit 1
+  end
 end
 
-puts "\nExcellent found #{excellent.errors.size} errors.\n"
-excellent.errors.each do |error|
-  puts "  * File #{error.filename}, line #{error.line_number}: #{error.message}"
+unless excellent.warnings.empty?
+  puts "\n  Warnings:\n\n"
+  excellent.warnings.each do |warning|
+    puts "  * File #{warning.filename}, line #{warning.line_number}: #{warning.message}"
+  end
 end
-puts ''
+puts "\n  Found #{excellent.warnings.size} warnings.\n\n"
 
 exit 0

data/lib/simplabs/excellent.rb

@@ -1,12 +1,14 @@
 require 'simplabs/excellent/checks'
-require 'simplabs/excellent/core'
+require 'simplabs/excellent/parsing'
 require 'rubygems'
 require 'sexp'
 
-module Excellent
+module Simplabs #:nodoc:
 
-  VERSION = '1.0.0'
+  module Excellent #:nodoc:
 
-end
+    VERSION = '1.2.0'
+
+  end
 
-Sexp.send(:include, Simplabs::Excellent::Core::VisitableSexp)
+end

data/lib/simplabs/excellent/checks.rb

@@ -1,9 +1,20 @@
+module Simplabs
+
+  module Excellent
+
+    module Checks #:nodoc:
+    end
+
+  end
+
+end
+
 require 'simplabs/excellent/checks/abc_metric_method_check'
 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/class_variable_check'
+require 'simplabs/excellent/checks/singleton_variable_check'
 require 'simplabs/excellent/checks/control_coupling_check'
 require 'simplabs/excellent/checks/cyclomatic_complexity_block_check'
 require 'simplabs/excellent/checks/cyclomatic_complexity_method_check'
@@ -14,3 +25,9 @@ require 'simplabs/excellent/checks/method_name_check'
 require 'simplabs/excellent/checks/module_line_count_check'
 require 'simplabs/excellent/checks/module_name_check'
 require 'simplabs/excellent/checks/parameter_number_check'
+require 'simplabs/excellent/checks/duplication_check'
+require 'simplabs/excellent/checks/nested_iterators_check'
+require 'simplabs/excellent/checks/flog_method_check'
+require 'simplabs/excellent/checks/flog_block_check'
+require 'simplabs/excellent/checks/flog_class_check'
+require 'simplabs/excellent/checks/rails'

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

@@ -6,70 +6,33 @@ module Simplabs
 
     module Checks
 
+      # This check reports methods with an ABC metric score that is higher than the threshold. The ABC metric is basically a measure for complexity
+      # and is calculated as:
+      #
+      #  a = number of assignments
+      #  b = number of branches
+      #  c = number of conditions
+      #
+      #  score = Math.sqrt(a*a + b*b + c*c)
+      #
+      # ==== Applies to
+      #
+      # * methods
       class AbcMetricMethodCheck < Base
 
-        ASSIGNMENTS       = [:lasgn]
-        BRANCHES          = [:vcall, :call]
-        CONDITIONS        = [:==, :<=, :>=, :<, :>]
-        OPERATORS         = [:*, :/, :%, :+, :<<, :>>, :&, :|, :^, :-, :**]
         DEFAULT_THRESHOLD = 10
 
-        def initialize(options = {})
+        def initialize(options = {}) #:nodoc:
           super()
-          @threshold = options[:threshold] || DEFAULT_THRESHOLD
+          @threshold         = options[:threshold] || DEFAULT_THRESHOLD
+          @interesting_nodes = [:defn, :defs]
         end
 
-        def interesting_nodes
-          [:defn]
-        end
-
-        def evaluate(node)
-          method_name = node[1]
-          a = count_assignments(node)
-          b = count_branches(node)
-          c = count_conditionals(node)
-          score = Math.sqrt(a*a + b*b + c*c)
-          add_error('Method {{method}} has abc score of {{score}}.', { :method => method_name, :score => score }) unless score <= @threshold
-        end
-
-        private
-
-          def count_assignments(node)
-            count = 0
-            count = count + 1 if assignment?(node)
-            node.children.each { |node| count += count_assignments(node) }
-            count
-          end
-
-          def count_branches(node)
-            count = 0
-            count = count + 1 if branch?(node)
-            node.children.each { |node| count += count_branches(node) }
-            count
-          end
-
-          def count_conditionals(node)
-            count = 0
-            count = count + 1 if conditional?(node)
-            node.children.each { |node| count += count_conditionals(node) }
-            count
+        def evaluate(context) #:nodoc:
+          unless context.abc_score <= @threshold
+            add_warning(context, '{{method}} has abc score of {{score}}.', { :method => context.full_name, :score => context.abc_score })
           end
-
-          def assignment?(node)
-            ASSIGNMENTS.include?(node.node_type)
-          end
-
-          def branch?(node)
-            BRANCHES.include?(node.node_type) && !conditional?(node) && !operator?(node)
-          end
-
-          def conditional?(node)
-            (:call == node.node_type) && CONDITIONS.include?(node[2]) 
-          end
-
-          def operator?(node)
-            (:call == node.node_type) && OPERATORS.include?(node[2]) 
-          end      
+        end
 
       end
 

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

@@ -6,29 +6,29 @@ module Simplabs
 
     module Checks
 
+      # This check reports conditionals that test an assignment as in
+      #
+      #  something(var) if var = method()
+      #
+      # Assignments in conditions are often typos.
+      #
+      # ==== Applies to
+      #
+      # * +if+
+      # * +else+
+      # * +while+
+      # * +until+
       class AssignmentInConditionalCheck < Base
 
-        def initialize(options = {})
+        def initialize(options = {}) #:nodoc:
           super()
+          @interesting_nodes = [:if, :while, :until]
         end
 
-        def interesting_nodes
-          [:if, :while, :until]
+        def evaluate(context) #:nodoc:
+          add_warning(context, 'Assignment in condition.') if context.tests_assignment?
         end
 
-        def evaluate(node)
-          add_error('Assignment in condition.') if has_assignment?(node[1])
-        end
-
-        private
-
-          def has_assignment?(node)
-            found_assignment = false
-            found_assignment = found_assignment || node.node_type == :lasgn
-            node.children.each { |child| found_assignment = found_assignment || has_assignment?(child) }
-            found_assignment
-          end
-
       end
 
     end

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

@@ -1,4 +1,4 @@
-require 'simplabs/excellent/core/error'
+require 'simplabs/excellent/warning'
 
 module Simplabs
 
@@ -6,33 +6,42 @@ module Simplabs
 
     module Checks
 
+      # This is the base class for all code checks. All checks must specify +interesting_nodes+. When one of these nodes is processed by Excellent, it
+      # will invoke the +evaluate_node+ method of all checks that specify the node as one if their +interesting_nodes+.
       class Base
 
-        def initialize
-          @errors = []
-        end
-  
-        def position(offset = 0)
-          "#{@line[2]}:#{@line[1] + offset}"
+        attr_reader :warnings
+
+        # An array of node types that are interesting for the check. These are symbols as returned by RubyParser (see http://parsetree.rubyforge.org/ruby_parser/),
+        # e.g. <tt>:if</tt> or <tt>:defn</tt>
+        attr_reader :interesting_nodes
+
+        def initialize #:nodoc:
+          @warnings = []
         end
-  
-        def evaluate_node(node)
-          @file = node.file
-          @line = node.line
-          eval_method = "evaluate_#{node.node_type}"
-          self.send(eval_method, node) if self.respond_to? eval_method
-          evaluate(node) if self.respond_to? :evaluate
+
+        # This method is called whenever Excellent processes a node that the check specified as one of the nodes it is interested in (see interesting_nodes).
+        #
+        # ==== Parameters
+        #
+        # * <tt>context</tt> - This is the last context the code processor has constructed. It contains all information required to execute the check (see Simplabs::Excellent::Parsing::SexpContext).
+        def evaluate_node(context)
+          evaluate(context)
         end
-  
-        def add_error(message, info = {}, offset = 0)
+
+        # Adds a warning
+        #
+        # ==== Parameters
+        #
+        # * <tt>context</tt> - The context the check has been executed on.
+        # * <tt>message</tt> - The warning message.
+        # * <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
-          @errors << Simplabs::Excellent::Core::Error.new(klass, message, @file, @line + offset, info)
+          @warnings << Simplabs::Excellent::Warning.new(klass, message, context.file, context.line + offset, info)
         end
   
-        def errors
-          @errors
-        end
-
       end
 
     end

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

@@ -6,14 +6,22 @@ module Simplabs
 
     module Checks
 
+      # This check reports +case+ statements that don't have an +else+ clause that would be executed when no case matches. If the tested value will never
+      # adopt any other values than the ones tested for in the cases, this should be expressed in the code by e.g. throwing an exception in the +else+
+      # clause.
+      #
+      # ==== Applies to
+      #
+      # * +case+ statements
       class CaseMissingElseCheck < Base
 
-        def interesting_nodes
-          [:case]
+        def initialize #:nodoc:
+          super
+          @interesting_nodes = [:case]
         end
-  
-        def evaluate(node)
-          add_error('Case statement is missing else clause.') unless node.last
+
+        def evaluate(context) #:nodoc:
+          add_warning(context, 'Case statement is missing else clause.') unless context.has_else_clause?
         end
 
       end

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

@@ -6,23 +6,25 @@ module Simplabs
 
     module Checks
 
+      # This check reports classes which have more lines than the threshold. Classes with a large number of lines are hard to read and understand and
+      # often an indicator for badly designed code as well.
+      #
+      # ==== Applies to
+      #
+      # * classes
       class ClassLineCountCheck < LineCountCheck
 
-        DEFAULT_THRESHOLD = 300
+        DEFAULT_THRESHOLD = 400
 
-        def initialize(options = {})
+        def initialize(options = {}) #:nodoc:
           threshold = options[:threshold] || DEFAULT_THRESHOLD
           super([:class], threshold)
         end
 
         protected
 
-          def node_to_count(node)
-            node[3]
-          end
-
-          def error_args(node, line_count)
-            ['Class {{class}} has {{count}} lines.', { :class => node[1], :count => line_count }]
+          def warning_args(context) #:nodoc:
+            [context, '{{class}} has {{count}} lines.', { :class => context.full_name, :count => context.line_count }]
           end
 
       end

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

@@ -6,26 +6,27 @@ module Simplabs
 
     module Checks
 
-      # Checks a class name to make sure it matches the specified pattern.
-      # 
-      # Keeping to a consistent naming convention makes your code easier to read.
+      # This check reports classes with bad names. Badly named classes make reading and understanding the code much harder. Class names regarded as bad
+      # are for example:
+      #
+      # * names that are not Pascal cased (camel cased, starting with an upper case letter)
+      #
+      # ==== Applies to
+      #
+      # * classes
       class ClassNameCheck < NameCheck
 
         DEFAULT_PATTERN = /^[A-Z]{1}[a-zA-Z0-9]*$/
       
-        def initialize(options = {})
+        def initialize(options = {}) #:nodoc:
           pattern = options[:pattern] || DEFAULT_PATTERN
           super([:class], pattern)
         end
       
-        def find_name(node)
-          node[1].class == Symbol ? node[1] : node[1].last
-        end
-
         protected
 
-          def error_args(node)
-            ['Bad class name {{class}}.', { :class => node[1] }]
+          def warning_args(context) #:nodoc:
+            [context, 'Bad class name {{class}}.', { :class => context.full_name }]
           end
 
       end