cane 1.4.0 → 2.0.0

data/HISTORY.md

@@ -1,5 +1,17 @@
 # Cane History
 
+## 2.0.0 - 19 August 2012 (35cae086)
+
+* ABC check labels  `MyClass = Struct.new {}` and `Class.new` correctly (#20)
+* Magic comments (`# encoding: utf-8`) are not recognized as appropriate class documentation (#21)
+* Invalid UTF-8 is handled correctly (#22)
+* Gracefully handle unknown options
+* ABC check output uses a standard format (Foo::Bar#method rather than Foo > Bar > method)
+* **BREAKING** Add `--abc-exclude`, `--style-exclude` CLI flags, remove YAML support
+* **BREAKING-INTERNAL** Use hashes rather than explicit violation classes
+* **BREAKING-INTERNAL** Remove translator class, pass CLI args direct to checks
+* **INTERNAL** Wiring in a new check only requires changing one file (#15)
+
 ## 1.4.0 - 2 July 2012 (1afc999d)
 
 * Allow files and methods to be whitelisted (#16)

data/README.md

@@ -16,8 +16,8 @@ a non-zero exit code if any quality checks fail. Also, a report:
 
     Methods exceeded maximum allowed ABC complexity (2):
 
-      lib/cane.rb  Cane > sample    23
-      lib/cane.rb  Cane > sample_2  17
+      lib/cane.rb  Cane#sample    23
+      lib/cane.rb  Cane#sample_2  17
 
     Lines violated style requirements (2):
 
@@ -36,21 +36,22 @@ Customize behaviour with a wealth of options:
 
             --abc-glob GLOB              Glob to run ABC metrics over (default: {app,lib}/**/*.rb)
             --abc-max VALUE              Ignore methods under this complexity (default: 15)
+            --abc-exclude METHOD         Exclude method from analysis (eg. Foo::Bar#method)
             --no-abc                     Disable ABC checking
 
-            --style-glob GLOB            Glob to run style metrics over (default: {app,lib,spec}/**/*.rb)
+            --style-glob GLOB            Glob to run style checks over (default: {app,lib,spec}/**/*.rb)
             --style-measure VALUE        Max line length (default: 80)
+            --style-exclude FILE         Exclude file from style checking
             --no-style                   Disable style checking
 
-            --doc-glob GLOB              Glob to run documentation checks over (default: {app,lib}/**/*.rb)
+            --doc-glob GLOB              Glob to run doc checks over (default: {app,lib}/**/*.rb)
             --no-doc                     Disable documentation checking
 
-            --gte FILE,THRESHOLD         If FILE contains a number, verify it is >= to THRESHOLD.
+            --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
+        -v, --version                    Show version
         -h, --help                       Show this message
 
 Set default options into a `.cane` file:
@@ -74,6 +75,7 @@ It works just like this:
         cane.abc_max = 10
         cane.add_threshold 'coverage/covered_percent', :>=, 99
         cane.no_style = true
+        cane.abc_exclude = %w(Foo::Bar.some_method)
       end
 
       task :default => :quality
@@ -118,24 +120,6 @@ 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.rb

@@ -1,12 +1,8 @@
-require 'cane/abc_check'
-require 'cane/style_check'
-require 'cane/doc_check'
-require 'cane/threshold_check'
 require 'cane/violation_formatter'
 
 module Cane
-  def run(opts)
-    Runner.new(opts).run
+  def run(*args)
+    Runner.new(*args).run
   end
   module_function :run
 
@@ -14,15 +10,9 @@ module Cane
   # hands the result to a formatter for display. This is the core of the
   # application, but for the actual entry point see `Cane::CLI`.
   class Runner
-    CHECKERS = {
-      abc:       AbcCheck,
-      style:     StyleCheck,
-      doc:       DocCheck,
-      threshold: ThresholdCheck
-    }
-
-    def initialize(opts)
+    def initialize(opts, checks)
       @opts = opts
+      @checks = checks
     end
 
     def run
@@ -33,12 +23,11 @@ module Cane
 
     protected
 
-    attr_reader :opts
+    attr_reader :opts, :checks
 
     def violations
-      @violations ||= CHECKERS.
-        select { |key, _| opts.has_key?(key) }.
-        map { |key, check| check.new(opts.fetch(key)).violations }.
+      @violations ||= checks.
+        map {|check| check.new(opts).violations }.
         flatten
     end
 

data/lib/cane/abc_check.rb

@@ -1,17 +1,41 @@
 require 'ripper'
-
-require 'cane/abc_max_violation'
-require 'cane/syntax_violation'
 require 'set'
 
+require 'cane/file'
+
 module Cane
 
   # Creates violations for methods that are too complicated using a simple
   # algorithm run against the parse tree of a file to count assignments,
   # branches, and conditionals. Borrows heavily from metric_abc.
   class AbcCheck < Struct.new(:opts)
+
+    def self.key; :abc; end
+    def self.name; "ABC check"; end
+    def self.options
+      {
+        abc_glob: ['Glob to run ABC metrics over',
+                      default: '{app,lib}/**/*.rb',
+                      variable: 'GLOB',
+                      clobber: :no_abc],
+        abc_max:  ['Ignore methods under this complexity',
+                      default: 15,
+                      cast:    :to_i,
+                      clobber: :no_abc],
+        abc_exclude: ['Exclude method from analysis (eg. Foo::Bar#method)',
+                         variable: 'METHOD',
+                         type: Array,
+                         default: [],
+                         clobber: :no_abc],
+        no_abc:   ['Disable ABC checking',
+                      cast: ->(x) { !x }]
+      }
+    end
+
     def violations
-      order file_names.map { |file_name|
+      return [] if opts[:no_abc] == false
+
+      order file_names.map {|file_name|
         find_violations(file_name)
       }.flatten
     end
@@ -19,7 +43,7 @@ module Cane
     protected
 
     def find_violations(file_name)
-      ast = Ripper::SexpBuilder.new(File.open(file_name, 'r:utf-8').read).parse
+      ast = Ripper::SexpBuilder.new(Cane::File.contents(file_name)).parse
       case ast
       when nil
         InvalidAst.new(file_name)
@@ -31,36 +55,51 @@ module Cane
     # Null object for when the file cannot be parsed.
     class InvalidAst < Struct.new(:file_name)
       def violations
-        [SyntaxViolation.new(file_name)]
+        [{file: file_name, description: "Files contained invalid syntax"}]
       end
     end
 
     # Wrapper object around sexps returned from ripper.
     class RubyAst < Struct.new(:file_name, :max_allowed_complexity,
                                :sexps, :exclusions)
+
+      def initialize(*args)
+        super
+        self.anon_method_add = true
+      end
+
       def violations
         process_ast(sexps).
-          select { |nesting, complexity| complexity > max_allowed_complexity }.
-          map { |x| AbcMaxViolation.new(file_name, x.first, x.last) }
+          select {|nesting, complexity| complexity > max_allowed_complexity }.
+          map {|x| {
+            file:        file_name,
+            label:       x.first,
+            value:       x.last,
+            description: "Methods exceeded maximum allowed ABC complexity"
+          }}
       end
 
       protected
 
+      # Stateful flag used to determine whether we are currently parsing an
+      # anonymous class. See #container_label.
+      attr_accessor :anon_method_add
+
       # Recursive function to process an AST. The `complexity` variable mutates,
       # which is a bit confusing. `nesting` does not.
       def process_ast(node, complexity = {}, nesting = [])
         if method_nodes.include?(node[0])
           nesting = nesting + [label_for(node)]
-          unless excluded?(node, *nesting)
-            complexity[nesting.join(" > ")] = calculate_abc(node)
+          desc = method_description(node, *nesting)
+          unless excluded?(desc)
+            complexity[desc] = calculate_abc(node)
           end
-        elsif container_nodes.include?(node[0])
-          parent  = node[1][-1][1]
+        elsif parent = container_label(node)
           nesting = nesting + [parent]
         end
 
         if node.is_a? Array
-          node[1..-1].each { |n| process_ast(n, complexity, nesting) if n }
+          node[1..-1].each {|n| process_ast(n, complexity, nesting) if n }
         end
         complexity
       end
@@ -73,6 +112,27 @@ module Cane
         abc
       end
 
+      def container_label(node)
+        if container_nodes.include?(node[0])
+          # def foo, def self.foo
+          node[1][-1][1]
+        elsif node[0] == :method_add_block
+          if anon_method_add
+            # Class.new do ...
+            "(anon)"
+          else
+            # MyClass = Class.new do ...
+            # parent already added when processing a parent node
+            anon_method_add = true
+            nil
+          end
+        elsif node[0] == :assign && node[2][0] == :method_add_block
+          # MyClass = Class.new do ...
+          self.anon_method_add = false
+          node[1][-1][1]
+        end
+      end
+
       def label_for(node)
         # A default case is deliberately omitted since I know of no way this
         # could fail and want it to fail fast.
@@ -82,7 +142,7 @@ module Cane
       end
 
       def count_nodes(node, types)
-        node.flatten.select { |n| types.include?(n) }.length
+        node.flatten.select {|n| types.include?(n) }.length
       end
 
       def assignment_nodes
@@ -107,27 +167,30 @@ module Cane
 
       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)
+      def excluded?(method_description)
+        exclusions.include?(method_description)
+      end
+
+      def method_description(node, *modules, meth_name)
+        separator = METH_CHARS.fetch(node.first)
+        description = [modules.join('::'), meth_name].join(separator)
       end
     end
 
     def file_names
-      Dir[opts.fetch(:files)]
+      Dir[opts.fetch(:abc_glob)]
     end
 
     def order(result)
-      result.sort_by(&:sort_index).reverse
+      result.sort_by {|x| x[:value].to_i }.reverse
     end
 
     def max_allowed_complexity
-      opts.fetch(:max)
+      opts.fetch(:abc_max)
     end
 
     def exclusions
-      opts.fetch(:exclusions, []).to_set
+      opts.fetch(:abc_exclude, []).flatten.to_set
     end
   end
 end

data/lib/cane/cli.rb

@@ -2,17 +2,15 @@ require 'cane'
 require 'cane/version'
 
 require 'cane/cli/spec'
-require 'cane/cli/translator'
 
 module Cane
   module CLI
-
     def run(args)
       opts = Spec.new.parse(args)
-      if opts
-        Cane.run(opts)
+      if opts.is_a?(Hash)
+        Cane.run(opts, Spec::CHECKS)
       else
-        true
+        opts
       end
     end
     module_function :run

data/lib/cane/cli/spec.rb

@@ -1,5 +1,9 @@
 require 'optparse'
-require 'cane/cli/translator'
+
+require 'cane/abc_check'
+require 'cane/style_check'
+require 'cane/doc_check'
+require 'cane/threshold_check'
 
 module Cane
   module CLI
@@ -7,14 +11,19 @@ module Cane
     # Provides a specification for the command line interface that drives
     # documentation, parsing, and default values.
     class Spec
-      DEFAULTS = {
-        abc_glob:       '{app,lib}/**/*.rb',
-        abc_max:        '15',
-        style_glob:     '{app,lib,spec}/**/*.rb',
-        style_measure:  '80',
-        doc_glob:       '{app,lib}/**/*.rb',
-        max_violations: '0',
-      }
+      CHECKS = [AbcCheck, StyleCheck, DocCheck, ThresholdCheck]
+
+      def self.defaults(check)
+        x = check.options.each_with_object({}) {|(k, v), h|
+          h[k] = (v[1] || {})[:default]
+        }
+        x
+      end
+
+      OPTIONS = {
+        max_violations:  0,
+        exclusions_file: nil,
+      }.merge(CHECKS.inject({}) {|a, check| a.merge(defaults(check)) })
 
       # Exception to indicate that no further processing is required and the
       # program can exit. This is used to handle --help and --version flags.
@@ -23,27 +32,31 @@ module Cane
       def initialize
         add_banner
 
-        add_abc_options
-        add_style_options
-        add_doc_options
-        add_threshold_options
+        CHECKS.each do |check|
+          add_check_options(check)
+        end
+
         add_cane_options
 
         add_version
         add_help
       end
 
-      def parse(args)
+      def parse(args, ret = true)
         parser.parse!(get_default_options + args)
 
-        Translator.new(options, DEFAULTS).to_hash
+        OPTIONS.merge(options)
+      rescue OptionParser::InvalidOption
+        args = %w(--help)
+        ret = false
+        retry
       rescue OptionsHandled
-        nil
+        ret
       end
 
       def get_default_options
-        if File.exists?('./.cane')
-          File.read('./.cane').gsub("\n", ' ').split(' ')
+        if ::File.exists?('./.cane')
+          ::File.read('./.cane').gsub("\n", ' ').split(' ')
         else
           []
         end
@@ -58,48 +71,38 @@ You can also put these options in a .cane file.
 BANNER
       end
 
-      def add_abc_options
-        add_option %w(--abc-glob GLOB), "Glob to run ABC metrics over"
-        add_option %w(--abc-max VALUE), "Ignore methods under this complexity"
-        add_option %w(--no-abc), "Disable ABC checking"
-
-        parser.separator ""
-      end
-
-      def add_style_options
-        add_option %w(--style-glob GLOB), "Glob to run style metrics over"
-        add_option %w(--style-measure VALUE), "Max line length"
-        add_option %w(--no-style), "Disable style checking"
-
-        parser.separator ""
-      end
-
-      def add_doc_options
-        add_option %w(--doc-glob GLOB), "Glob to run documentation checks over"
-        add_option %w(--no-doc), "Disable documentation checking"
-
-        parser.separator ""
-      end
-
-      def add_threshold_options
-        desc = "If FILE contains a number, verify it is >= to THRESHOLD."
-        parser.on("--gte FILE,THRESHOLD", Array, desc) do |opts|
-          (options[:threshold] ||= []) << opts.unshift(:>=)
+      def add_check_options(check)
+        check.options.each do |key, data|
+          cli_key  = key.to_s.tr('_', '-')
+          opts     = data[1] || {}
+          variable = opts[:variable] || "VALUE"
+          defaults = opts[:default] || []
+
+          if opts[:type] == Array
+            parser.on("--#{cli_key} #{variable}", Array, data[0]) do |opts|
+              (options[key.to_sym] ||= []) << opts
+            end
+          else
+            if [*defaults].length > 0
+              add_option ["--#{cli_key}", variable], *data
+            else
+              add_option ["--#{cli_key}"], *data
+            end
+          end
         end
 
         parser.separator ""
       end
 
       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"
+        add_option %w(--max-violations VALUE),
+          "Max allowed violations", default: 0, cast: :to_i
 
         parser.separator ""
       end
 
       def add_version
-        parser.on_tail("--version", "Show version") do
+        parser.on_tail("-v", "--version", "Show version") do
           puts Cane::VERSION
           raise OptionsHandled
         end
@@ -112,15 +115,18 @@ BANNER
         end
       end
 
-      def add_option(option, description)
+      def add_option(option, description, opts={})
         option_key = option[0].gsub('--', '').tr('-', '_').to_sym
+        default    = opts[:default]
+        cast       = opts[:cast] || ->(x) { x }
 
-        if DEFAULTS.has_key?(option_key)
-          description += " (default: %s)" % DEFAULTS[option_key]
+        if default
+          description += " (default: %s)" % default
         end
 
         parser.on(option.join(' '), description) do |v|
-          options[option_key] = v
+          options[option_key] = cast.to_proc.call(v)
+          options.delete(opts[:clobber])
         end
       end