cane 2.5.2 → 2.6.0

data/HISTORY.md

@@ -1,5 +1,15 @@
 # Cane History
 
+## 2.6.0 - 7 June 2013 (616bb8a5)
+
+* Feature: classes with no methods do not require documentation.
+* Feature: modules with methods require documentation.
+* Feature: support all README extensions.
+* Feature: --color option.
+* Bugfix: fix false positive on class matching for doc check.
+* Bugfix: better handling of invalid strings.
+* Compat: fix Ruby 2.0 deprecations.
+
 ## 2.5.2 - 26 January 2013 (a0cf38ba)
 
 * Feature: support operators beside `>=` in threshold check.

data/README.md

@@ -62,6 +62,7 @@ Customize behaviour with a wealth of options:
         --max-violations VALUE       Max allowed violations (default: 0)
         --json                       Output as JSON
         --parallel                   Use all processors. Slower on small projects, faster on large.
+        --color                      Colorize output
 
     -v, --version                    Show version
     -h, --help                       Show this message

data/lib/cane/cli.rb

@@ -4,6 +4,8 @@ require 'cane/version'
 require 'cane/cli/parser'
 
 module Cane
+  # Command line interface. This passes off arguments to the parser and starts
+  # the Cane runner
   module CLI
     def run(args)
       spec = Parser.parse(args)

data/lib/cane/cli/options.rb

@@ -1,6 +1,7 @@
 require 'cane/default_checks'
 
 module Cane
+  # Default options for command line interface
   module CLI
     def defaults(check)
       check.options.each_with_object({}) {|(k, v), h|

data/lib/cane/cli/parser.rb

@@ -118,6 +118,9 @@ BANNER
           "Use all processors. Slower on small projects, faster on large.",
             cast: ->(x) { x }
 
+        add_option %w(--color),
+          "Colorize output", default: false
+
         parser.separator ""
       end
 

data/lib/cane/default_checks.rb

@@ -3,6 +3,7 @@ require 'cane/style_check'
 require 'cane/doc_check'
 require 'cane/threshold_check'
 
+# Default checks performed when no checks are provided
 module Cane
   def default_checks
     [

data/lib/cane/doc_check.rb

@@ -8,7 +8,15 @@ module Cane
   class DocCheck < Struct.new(:opts)
 
     DESCRIPTION =
-      "Class definitions require explanatory comments on preceding line"
+    "Class and Module definitions require explanatory comments on previous line"
+
+    ClassDefinition = Struct.new(:values) do
+      def line; values.fetch(:line); end
+      def label; values.fetch(:label); end
+      def missing_doc?; !values.fetch(:has_doc); end
+      def requires_doc?; values.fetch(:requires_doc, false); end
+      def requires_doc=(value); values[:requires_doc] = value; end
+    end
 
     def self.key; :doc; end
     def self.name; "documentation checking"; end
@@ -33,6 +41,10 @@ module Cane
     MAGIC_COMMENT_REGEX =
       %r"#(\s+-\*-)?\s+(en)?coding\s*[=:]\s*([[:alnum:]\-_]+)"
 
+    CLASS_REGEX = /^\s*(?:class|module)\s+([^\s;]+)/
+
+    METHOD_REGEX = /(?:^|\s)def\s+/
+
     def violations
       return [] if opts[:no_doc]
 
@@ -42,30 +54,46 @@ module Cane
     end
 
     def find_violations(file_name)
-      last_line = ""
-      Cane::File.iterator(file_name).map.with_index do |line, number|
-        result = if class_definition?(line) && !comment?(last_line)
+      class_definitions_in(file_name).map do |class_definition|
+        if class_definition.requires_doc? && class_definition.missing_doc?
           {
             file:        file_name,
-            line:        number + 1,
-            label:       extract_class_name(line),
+            line:        class_definition.line,
+            label:       class_definition.label,
             description: DESCRIPTION
           }
         end
-        last_line = line
-        result
       end.compact
     end
 
+    def class_definitions_in(file_name)
+      class_definitions = []
+      last_line = ""
+
+      Cane::File.iterator(file_name).each_with_index do |line, number|
+        if class_definition? line
+          class_definitions << ClassDefinition.new({
+            line: (number + 1),
+            label: extract_class_name(line),
+            has_doc: comment?(last_line)
+          })
+        end
+
+        if method_definition?(line) && !class_definitions.empty?
+          class_definitions.last.requires_doc = true
+        end
+
+        last_line = line
+      end
+
+      class_definitions
+    end
+
     def missing_file_violations
       result = []
       return result if opts[:no_readme]
 
-      filenames = ['README', 'readme']
-      extensions = ['', '.txt', '.md', '.mdown', '.rdoc']
-      combinations = filenames.product(extensions)
-
-      if combinations.none? {|n, x| Cane::File.exists?(n + x) }
+      if Cane::File.case_insensitive_glob("README*").none?
         result << { description: 'Missing documentation',
                     label: 'No README found' }
       end
@@ -76,8 +104,12 @@ module Cane
       Dir[opts.fetch(:doc_glob)].reject { |file| excluded?(file) }
     end
 
+    def method_definition?(line)
+      line =~ METHOD_REGEX
+    end
+
     def class_definition?(line)
-      line =~ /^\s*class\s+/ and $'.index('<<') != 0
+      line =~ CLASS_REGEX && $1.index('<<') != 0
     end
 
     def comment?(line)
@@ -85,7 +117,7 @@ module Cane
     end
 
     def extract_class_name(line)
-      line.match(/class\s+([^\s;]+)/)[1]
+      line.match(CLASS_REGEX)[1]
     end
 
     def exclusions
@@ -102,5 +134,4 @@ module Cane
       Cane.task_runner(opts)
     end
   end
-
 end

data/lib/cane/encoding_aware_iterator.rb

@@ -9,13 +9,13 @@ module Cane
     end
 
     def each(&block)
-      return Enumerator.new(self, :each) unless block
+      return self.to_enum unless block
 
       lines.each do |line|
         begin
           line =~ /\s/
         rescue ArgumentError
-          line.encode!('UTF-8', 'UTF-8', invalid: :replace)
+          line.encode!('UTF-8', 'binary', invalid: :replace, undef: :replace)
         end
 
         block.call(line)

data/lib/cane/file.rb

@@ -21,6 +21,10 @@ module Cane
       def exists?(path)
         ::File.exists?(path)
       end
+
+      def case_insensitive_glob(glob)
+        Dir.glob(glob, ::File::FNM_CASEFOLD)
+      end
     end
   end
 end

data/lib/cane/rake_task.rb

@@ -54,7 +54,11 @@ module Cane
       @gte = []
       @options = Cane::CLI.default_options
 
-      yield self if block_given?
+      if block_given?
+        yield self
+      else
+        self.canefile = './.cane'
+      end
 
       unless ::Rake.application.last_comment
         desc %(Check code quality metrics with cane)

data/lib/cane/runner.rb

@@ -3,6 +3,7 @@ require 'parallel'
 require 'cane/violation_formatter'
 require 'cane/json_formatter'
 
+# Accepts a parsed configuration and passes those options to a new Runner
 module Cane
   def run(*args)
     Runner.new(*args).run
@@ -19,7 +20,7 @@ module Cane
     end
 
     def run
-      outputter.print formatter.new(violations)
+      outputter.print formatter.new(violations, opts)
 
       violations.length <= opts.fetch(:max_violations)
     end

data/lib/cane/task_runner.rb

@@ -1,3 +1,4 @@
+# Provides a SimpleTaskRunner or Parallel task runner based on configuration
 module Cane
   def task_runner(opts)
     if opts[:parallel]
@@ -8,7 +9,7 @@ module Cane
   end
   module_function :task_runner
 
-  # Mirrors the Parallel gem's interface but does not provide any parralleism.
+  # Mirrors the Parallel gem's interface but does not provide any parallelism.
   # This is faster for smaller tasks since it doesn't incur any overhead for
   # creating new processes and communicating between them.
   class SimpleTaskRunner

data/lib/cane/version.rb

@@ -1,3 +1,3 @@
 module Cane
-  VERSION = '2.5.2'
+  VERSION = '2.6.0'
 end

data/lib/cane/violation_formatter.rb

@@ -6,24 +6,32 @@ module Cane
   # Computes a string to be displayed as output from an array of violations
   # computed by the checks.
   class ViolationFormatter
-    attr_reader :violations
+    attr_reader :violations, :options
 
-    def initialize(violations)
+    def initialize(violations, options = {})
       @violations = violations.map do |v|
         v.merge(file_and_line: v[:line] ?
           "%s:%i" % v.values_at(:file, :line) :
           v[:file]
         )
       end
+
+      @options = options
     end
 
     def to_s
       return "" if violations.empty?
 
-      violations.group_by {|x| x[:description] }.map do |d, vs|
+      string = violations.group_by {|x| x[:description] }.map do |d, vs|
         format_group_header(d, vs) +
           format_violations(vs)
       end.join("\n") + "\n\n" + totals + "\n\n"
+
+      if violations.count > options.fetch(:max_violations, 0)
+        string = colorize(string)
+      end
+
+      string
     end
 
     protected
@@ -54,6 +62,12 @@ module Cane
       }.join('  ').strip
     end
 
+    def colorize(string)
+      return string unless options[:color]
+
+      "\e[31m#{string}\e[0m"
+    end
+
     def totals
       "Total Violations: #{violations.length}"
     end

data/spec/cane_spec.rb

@@ -50,8 +50,10 @@ describe 'The cane application' do
       --unhappy-file #{fn}
     )
     output.should include("Lines violated style requirements")
-    output.should include("Class definitions require explanatory comments")
     output.should include("Methods exceeded maximum allowed ABC complexity")
+    output.should include(
+      "Class and Module definitions require explanatory comments"
+    )
     exitstatus.should == 1
   end
 
@@ -69,6 +71,12 @@ describe 'The cane application' do
     Cane.task_runner(parallel: true).should == Parallel
   end
 
+  it 'colorizes output' do
+    output, exitstatus = run("--color --abc-max 0")
+
+    output.should include("\e[31m")
+  end
+
   after do
     if Object.const_defined?(class_name)
       Object.send(:remove_const, class_name)

data/spec/doc_check_spec.rb

@@ -7,38 +7,60 @@ describe Cane::DocCheck do
     described_class.new(opts.merge(doc_glob: file_name))
   end
 
-  it 'creates a DocViolation for each undocumented class' do
+  it 'creates a DocViolation for each undocumented class with a method' do
     file_name = make_file <<-RUBY
 # This class is documented
 class Doc; end
-class  NoDoc; end # No doc
-  class AlsoNoDoc; end
+class  Empty; end # No doc is fine
+  class NoDoc; def with_method; end; end
 classIgnore = nil
 [:class]
 # class Ignore
 class Meta
   class << self; end
+end
+module DontNeedDoc; end
+# This module is documented
+module HasDoc
+  def mixin; end
+end
+module AlsoNeedsDoc; def mixin; end; end
+module NoDocIsFine
+  module ButThisNeedsDoc
+    def self.global
+    end
+  end
+  module AlsoNoDocIsFine; end
+  # We've got docs
+  module CauseWeNeedThem
+    def mixin
+    end
+  end
 end
     RUBY
 
     violations = check(file_name).violations
-    violations.length.should == 2
+    violations.length.should == 3
 
     violations[0].values_at(:file, :line, :label).should == [
-      file_name, 3, "NoDoc"
+      file_name, 4, "NoDoc"
     ]
 
     violations[1].values_at(:file, :line, :label).should == [
-      file_name, 4, "AlsoNoDoc"
+      file_name, 16, "AlsoNeedsDoc"
+    ]
+
+    violations[2].values_at(:file, :line, :label).should == [
+      file_name, 18, "ButThisNeedsDoc"
     ]
   end
 
   it 'ignores magic encoding comments' do
     file_name = make_file <<-RUBY
 # coding = utf-8
-class NoDoc; end
+class NoDoc; def do_stuff; end; end
 # -*-  encoding :  utf-8  -*-
-class AlsoNoDoc; end
+class AlsoNoDoc; def do_more_stuff; end; end
 # Parse a Transfer-Encoding: Chunked response
 class Doc; end
     RUBY
@@ -57,16 +79,7 @@ class Doc; end
   it 'creates a violation for missing README' do
     file = fire_replaced_class_double("Cane::File")
     stub_const("Cane::File", file)
-    file.should_receive(:exists?).with("README").and_return(false)
-    file.should_receive(:exists?).with("README.md").and_return(false)
-    file.should_receive(:exists?).with("README.mdown").and_return(false)
-    file.should_receive(:exists?).with("README.txt").and_return(false)
-    file.should_receive(:exists?).with("README.rdoc").and_return(false)
-    file.should_receive(:exists?).with("readme").and_return(false)
-    file.should_receive(:exists?).with("readme.md").and_return(false)
-    file.should_receive(:exists?).with("readme.mdown").and_return(false)
-    file.should_receive(:exists?).with("readme.txt").and_return(false)
-    file.should_receive(:exists?).with("readme.rdoc").and_return(false)
+    file.should_receive(:case_insensitive_glob).with("README*").and_return([])
 
     violations = check("").violations
     violations.length.should == 1
@@ -76,6 +89,18 @@ class Doc; end
     ]
   end
 
+  it 'does not create a violation when readme exists' do
+    file = fire_replaced_class_double("Cane::File")
+    stub_const("Cane::File", file)
+    file
+      .should_receive(:case_insensitive_glob)
+      .with("README*")
+      .and_return(%w(readme.md))
+
+    violations = check("").violations
+    violations.length.should == 0
+  end
+
   it 'skips declared exclusions' do
     file_name = make_file <<-FILE.gsub /^\s{6}/, ''
       class NeedsDocumentation
@@ -101,4 +126,16 @@ class Doc; end
 
     violations.length.should == 0
   end
+
+  it 'skips class inside an array' do
+    file_name = make_file <<-RUBY
+    %w(
+      class
+      method
+    )
+    RUBY
+
+    violations = check(file_name).violations
+    violations.length.should == 0
+  end
 end

data/spec/file_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+require 'tmpdir'
+
+require 'cane/file'
+
+describe Cane::File do
+  describe '.case_insensitive_glob' do
+    it 'matches all kinds of readmes' do
+      expected = %w(
+        README
+        readme.md
+        ReaDME.TEXTILE
+      )
+
+      Dir.mktmpdir do |dir|
+        Dir.chdir(dir) do
+          expected.each do |x|
+            FileUtils.touch(x)
+          end
+          Cane::File.case_insensitive_glob("README*").should =~ expected
+        end
+      end
+    end
+  end
+end

data/spec/rake_task_spec.rb

@@ -47,6 +47,22 @@ describe Cane::RakeTask do
     out.should include("Quality threshold crossed")
   end
 
+  it 'defaults to using a canefile without a block' do
+    in_tmp_dir do
+      conf = "--gte 90,99"
+      conf_file = File.open('.cane', 'w') {|f| f.write conf }
+
+      task = Cane::RakeTask.new(:canefile_quality)
+
+      task.should_receive(:abort)
+      out = capture_stdout do
+        Rake::Task['canefile_quality'].invoke
+      end
+
+      out.should include("Quality threshold crossed")
+    end
+  end
+
   after do
     Rake::Task.clear
   end

data/spec/spec_helper.rb

@@ -28,6 +28,12 @@ def make_file(content)
   tempfile.path
 end
 
+def in_tmp_dir(&block)
+  Dir.mktmpdir do |dir|
+    Dir.chdir(dir, &block)
+  end
+end
+
 RSpec::Matchers.define :have_violation do |label|
   match do |check|
     violations = check.violations

data/spec/violation_formatter_spec.rb

@@ -18,4 +18,22 @@ describe Cane::ViolationFormatter do
     result = described_class.new(violations).to_s
     result.should include("Total Violations: 2")
   end
+
+  it 'does not colorize output by default' do
+    result = described_class.new([violation("FAIL")]).to_s
+    result.should_not include("\e[31m")
+  end
+
+  it 'colorizes output when passed color: true' do
+    result = described_class.new([violation("FAIL")], color: true).to_s
+    result.should include("\e[31m")
+    result.should include("\e[0m")
+  end
+
+  it 'does not colorize output if max_violations is not crossed' do
+    options = { color: true, max_violations: 1 }
+    result = described_class.new([violation("FAIL")], options).to_s
+
+    result.should_not include("\e[31m")
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cane
 version: !ruby/object:Gem::Version
-  version: 2.5.2
+  version: 2.6.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-26 00:00:00.000000000 Z
+date: 2013-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parallel
@@ -104,6 +104,7 @@ files:
 - spec/cli_spec.rb
 - spec/doc_check_spec.rb
 - spec/encoding_aware_iterator_spec.rb
+- spec/file_spec.rb
 - spec/json_formatter_spec.rb
 - spec/parser_spec.rb
 - spec/rake_task_spec.rb
@@ -165,6 +166,7 @@ test_files:
 - spec/cli_spec.rb
 - spec/doc_check_spec.rb
 - spec/encoding_aware_iterator_spec.rb
+- spec/file_spec.rb
 - spec/json_formatter_spec.rb
 - spec/parser_spec.rb
 - spec/rake_task_spec.rb