cane 1.3.0 → 1.4.0

data/HISTORY.md

@@ -1,5 +1,10 @@
 # Cane History
 
+## 1.4.0 - 2 July 2012 (1afc999d)
+
+* Allow files and methods to be whitelisted (#16)
+* Show total number of violations in output (#14)
+
 ## 1.3.0 - 20 April 2012 (c166dfa0)
 
 * Remove dependency on tailor. Fewer styles checks are performed, but the three

data/README.md

@@ -48,6 +48,7 @@ Customize behaviour with a wealth of options:
             --gte FILE,THRESHOLD         If FILE contains a number, verify it is >= to THRESHOLD.
 
             --max-violations VALUE       Max allowed violations (default: 0)
+            --exclusions-file FILE       YAML file containing a list of exclusions
 
             --version                    Show version
         -h, --help                       Show this message
@@ -91,6 +92,8 @@ on to an existing application that may already have many violations. By setting
 the maximum to the current number, no immediate changes will be required to
 your existing code base, but you will be protected from things getting worse.
 
+You can also consider defining exclusions for each violation (see below).
+
 ## Integrating with SimpleCov
 
 Any value in a file can be used as a threshold:
@@ -115,6 +118,24 @@ You can use a `SimpleCov` formatter to create the required file:
 
     SimpleCov.formatter = SimpleCov::Formatter::QualityFormatter
 
+## Defining Exclusions
+
+Occasionally, you may want to permanently ignore specific cane violations.
+Create a YAML file like so:
+
+    abc:
+      - Some::Fully::Qualified::Class.some_class_method
+      - Some::Fully::Qualified::Class#some_instance_method
+    style:
+      relative/path/to/some/file.rb
+      relative/path/to/some/other/file.rb
+
+Tell cane about this file using the `--exclusions-file` option:
+
+    > cane --exclusions-file path/to/exclusions.yml
+
+Currently, only the abc and style checks support exclusions.
+
 ## Compatibility
 
 Requires MRI 1.9, since it depends on the `ripper` library to calculate

data/lib/cane/abc_check.rb

@@ -2,6 +2,7 @@ require 'ripper'
 
 require 'cane/abc_max_violation'
 require 'cane/syntax_violation'
+require 'set'
 
 module Cane
 
@@ -23,7 +24,7 @@ module Cane
       when nil
         InvalidAst.new(file_name)
       else
-        RubyAst.new(file_name, max_allowed_complexity, ast)
+        RubyAst.new(file_name, max_allowed_complexity, ast, exclusions)
       end.violations
     end
 
@@ -35,7 +36,8 @@ module Cane
     end
 
     # Wrapper object around sexps returned from ripper.
-    class RubyAst < Struct.new(:file_name, :max_allowed_complexity, :sexps)
+    class RubyAst < Struct.new(:file_name, :max_allowed_complexity,
+                               :sexps, :exclusions)
       def violations
         process_ast(sexps).
           select { |nesting, complexity| complexity > max_allowed_complexity }.
@@ -49,7 +51,9 @@ module Cane
       def process_ast(node, complexity = {}, nesting = [])
         if method_nodes.include?(node[0])
           nesting = nesting + [label_for(node)]
-          complexity[nesting.join(" > ")] = calculate_abc(node)
+          unless excluded?(node, *nesting)
+            complexity[nesting.join(" > ")] = calculate_abc(node)
+          end
         elsif container_nodes.include?(node[0])
           parent  = node[1][-1][1]
           nesting = nesting + [parent]
@@ -100,6 +104,14 @@ module Cane
       def condition_nodes
         [:==, :===, :"<>", :"<=", :">=", :"=~", :>, :<, :else, :"<=>"]
       end
+
+      METH_CHARS = { def: '#', defs: '.' }
+
+      def excluded?(node, *modules, meth_name)
+        meth_char = METH_CHARS.fetch(node.first)
+        description = [modules.join('::'), meth_name].join(meth_char)
+        exclusions.include?(description)
+      end
     end
 
     def file_names
@@ -113,5 +125,9 @@ module Cane
     def max_allowed_complexity
       opts.fetch(:max)
     end
+
+    def exclusions
+      opts.fetch(:exclusions, []).to_set
+    end
   end
 end

data/lib/cane/cli/spec.rb

@@ -92,6 +92,8 @@ BANNER
 
       def add_cane_options
         add_option %w(--max-violations VALUE), "Max allowed violations"
+        add_option %w(--exclusions-file FILE),
+                   "YAML file containing a list of exclusions"
 
         parser.separator ""
       end

data/lib/cane/cli/translator.rb

@@ -1,3 +1,5 @@
+require 'yaml'
+
 module Cane
   module CLI
 
@@ -18,15 +20,17 @@ module Cane
 
       def translate_abc_options(result)
         result[:abc] = {
-          files: option_with_default(:abc_glob),
-          max:   option_with_default(:abc_max).to_i
+          files:      option_with_default(:abc_glob),
+          max:        option_with_default(:abc_max).to_i,
+          exclusions: exclusions_for('abc')
         } unless check_disabled(:no_abc, [:abc_glob, :abc_max])
       end
 
       def translate_style_options(result)
         result[:style] = {
-          files:   option_with_default(:style_glob),
-          measure: option_with_default(:style_measure).to_i,
+          files:      option_with_default(:style_glob),
+          measure:    option_with_default(:style_measure).to_i,
+          exclusions: exclusions_for('style')
         } unless check_disabled(:no_style, [:style_glob])
       end
 
@@ -45,6 +49,22 @@ module Cane
       def option_with_default(key)
         options.fetch(key, defaults.fetch(key))
       end
+
+    private
+
+      def exclusions_for(tool)
+        Array(exclusions[tool])
+      end
+
+      def exclusions
+        @exclusions ||= begin
+          if file = options[:exclusions_file]
+            YAML.load_file(file)
+          else
+            {}
+          end
+        end
+      end
     end
 
   end

data/lib/cane/doc_check.rb

@@ -44,7 +44,7 @@ module Cane
     end
 
     def extract_class_name(line)
-      line.match(/class (\S+)/)[1]
+      line.match(/class ([^\s;]+)/)[1]
     end
   end
 

data/lib/cane/rake_task.rb

@@ -32,6 +32,8 @@ module Cane
     attr_accessor :no_doc
     # Max violations to tolerate (default: 0)
     attr_accessor :max_violations
+    # File containing list of exclusions in YAML format
+    attr_accessor :exclusions_file
 
     # Add a threshold check. If the file exists and it contains a number,
     # compare that number with the given value using the operator.
@@ -63,7 +65,8 @@ module Cane
         :max_violations,
         :style_glob,
         :no_style,
-        :style_measure
+        :style_measure,
+        :exclusions_file
       ].inject(threshold: @threshold) do |opts, setting|
         value = self.send(setting)
         opts[setting] = value unless value.nil?

data/lib/cane/style_check.rb

@@ -1,11 +1,12 @@
 require 'cane/style_violation'
+require 'set'
 
 module Cane
 
   # Creates violations for files that do not meet style conventions. Only
   # highly obvious, probable, and non-controversial checks are performed here.
   # It is not the goal of the tool to provide an extensive style report, but
-  # only to prevent studid mistakes.
+  # only to prevent stupid mistakes.
   class StyleCheck < Struct.new(:opts)
     def violations
       file_list.map do |file_path|
@@ -30,7 +31,7 @@ module Cane
     end
 
     def file_list
-      Dir[opts.fetch(:files)]
+      Dir[opts.fetch(:files)].reject { |f| excluded?(f) }
     end
 
     def measure
@@ -40,6 +41,14 @@ module Cane
     def map_lines(file_path, &block)
       File.open(file_path).each_line.map.with_index(&block)
     end
+
+    def exclusions
+      @exclusions ||= opts.fetch(:exclusions, []).to_set
+    end
+
+    def excluded?(file)
+      exclusions.include?(file)
+    end
   end
 
 end

data/lib/cane/version.rb

@@ -1,3 +1,3 @@
 module Cane
-  VERSION = '1.3.0'
+  VERSION = '1.4.0'
 end

data/lib/cane/violation_formatter.rb

@@ -11,11 +11,15 @@ module Cane
       grouped_violations.map do |description, violations|
         format_group_header(description, violations) +
           format_violations(violations)
-      end.flatten.join("\n") + "\n\n"
+      end.flatten.join("\n") + "\n\n" + totals + "\n\n"
     end
 
     protected
 
+    def totals
+      "Total Violations: #{violations.count}"
+    end
+
     def format_group_header(description, violations)
       ["", "%s (%i):" % [description, violations.length], ""]
     end

data/spec/abc_check_spec.rb

@@ -55,6 +55,43 @@ describe Cane::AbcCheck do
     violations[0].description.should be_instance_of(String)
   end
 
+  it 'skips declared exclusions' do
+    file_name = make_file(<<-RUBY)
+      class Harness
+        def instance_meth
+          true
+        end
+
+        def self.class_meth
+          true
+        end
+
+        module Nested
+          def i_meth
+            true
+          end
+
+          def self.c_meth
+            true
+          end
+
+          def other_meth
+            true
+          end
+        end
+      end
+    RUBY
+
+    exclusions = %w[ Harness#instance_meth  Harness.class_meth
+                     Harness::Nested#i_meth Harness::Nested.c_meth ]
+    violations = described_class.new(files: file_name, max: 0,
+                                     exclusions: exclusions).violations
+    violations.length.should == 1
+    violations[0].should be_instance_of(Cane::AbcMaxViolation)
+    columns = violations[0].columns
+    columns.should == [file_name, "Harness > Nested > other_meth", 1]
+  end
+
   def self.it_should_extract_method_name(method_name, label=method_name)
     it "creates an AbcMaxViolation for #{method_name}" do
       file_name = make_file(<<-RUBY)

data/spec/cane_spec.rb

@@ -127,4 +127,37 @@ describe 'Cane' do
     run("--no-doc --doc-glob #{file_name}").should ==
       run("--doc-glob #{file_name}")
   end
+
+  it 'supports exclusions' do
+    line_with_whitespace = "whitespace "
+    file_name = make_file(<<-RUBY)
+      # #{line_with_whitespace}
+      class Harness
+        def complex_method(a)
+          if a < 2
+            return "low"
+          else
+            return "high"
+          end
+        end
+      end
+    RUBY
+
+    exclusions_file = make_file(<<-YAML)
+abc:
+  - Harness#complex_method
+style:
+  - #{file_name}
+    YAML
+
+    options = [
+      "--abc-glob", file_name,
+      "--abc-max", 1,
+      "--style-glob", file_name,
+      "--exclusions-file", exclusions_file
+    ].join(' ')
+
+    _, exitstatus = run(options)
+    exitstatus.should == 0
+  end
 end

data/spec/doc_check_spec.rb

@@ -22,9 +22,11 @@ end
     violations[0].should be_instance_of(Cane::UndocumentedClassViolation)
     violations[0].file_name.should == file_name
     violations[0].number.should == 3
+    violations[0].columns.last.should eq("NoDoc")
 
     violations[1].should be_instance_of(Cane::UndocumentedClassViolation)
     violations[1].file_name.should == file_name
     violations[1].number.should == 4
+    violations[1].columns.last.should eq("AlsoNoDoc")
   end
 end

data/spec/style_check_spec.rb

@@ -3,16 +3,27 @@ require 'spec_helper'
 require 'cane/style_check'
 
 describe Cane::StyleCheck do
-  it 'creates a StyleViolation for each method above the threshold' do
-    ruby = [
+  let(:ruby_with_style_issue) do
+    [
       "def test  ",
       "\t1",
       "end"
     ].join("\n")
-    file_name = make_file(ruby)
+  end
+
+  it 'creates a StyleViolation for each method above the threshold' do
+    file_name = make_file(ruby_with_style_issue)
 
     violations = Cane::StyleCheck.new(files: file_name, measure: 80).violations
     violations.length.should == 2
     violations[0].should be_instance_of(StyleViolation)
   end
+
+  it 'skips declared exclusions' do
+    file_name = make_file(ruby_with_style_issue)
+
+    violations = Cane::StyleCheck.new(files: file_name, measure: 80,
+                                      exclusions: [file_name]).violations
+    violations.length.should == 0
+  end
 end

data/spec/violation_formatter_spec.rb

@@ -13,4 +13,10 @@ describe Cane::ViolationFormatter do
   it 'includes number of violations in the group header' do
     described_class.new([violation("FAIL")]).to_s.should include("(1)")
   end
+
+  it 'includes total number of violations' do
+    violations = [violation("FAIL1"),violation("FAIL2")]
+    result = described_class.new(violations).to_s
+    result.should include("Total Violations: 2")
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cane
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-21 00:00:00.000000000 Z
+date: 2012-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -114,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Fails your build if code quality thresholds are not met. Provides complexity