sparqcode_cane 1.3.0.1

data/HISTORY.md

@@ -0,0 +1,24 @@
+# Cane History
+
+## 1.3.0 - 20 April 2012 (c166dfa0)
+
+* Remove dependency on tailor. Fewer styles checks are performed, but the three
+  remaining are the only ones I've found useful.
+
+## 1.2.0 - 31 March 2012 (adce51b9)
+
+* Gracefully handle files with invalid syntax (#1)
+* Included class methods in ABC check (#8)
+* Can disable style and doc checks from rake task (#9)
+
+## 1.1.0 - 24 March 2012 (ba8a74fc)
+
+* `app` added to default globs
+* Added `cane/rake_task`
+* `class << obj` syntax ignore by documentation check
+* Line length checks no longer include trailing new lines
+* Add support for a `.cane` file for setting per-project default options.
+
+## 1.0.0 - 14 January 2012 (4e400534)
+
+* Initial release.

data/LICENSE

@@ -0,0 +1,14 @@
+
+   Copyright 2012 Square Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,136 @@
+# Cane
+
+Fails your build if code quality thresholds are not met.
+
+> Discipline will set you free.
+
+## Usage
+
+    gem install cane
+    cane --abc-glob '{lib,spec}/**/*.rb' --abc-max 15
+
+Your main build task should run this, probably via `bundle exec`. It will have
+a non-zero exit code if any quality checks fail. Also, a report:
+
+    > cane
+
+    Methods exceeded maximum allowed ABC complexity (2):
+
+      lib/cane.rb  Cane > sample    23
+      lib/cane.rb  Cane > sample_2  17
+
+    Lines violated style requirements (2):
+
+      lib/cane.rb:20   Line length >80
+      lib/cane.rb:42   Trailing whitespace
+
+    Classes are not documented (1):
+      lib/cane:3  SomeClass
+
+Customize behaviour with a wealth of options:
+
+    > cane --help
+    Usage: cane [options]
+
+    You can also put these options in a .cane file.
+
+            --abc-glob GLOB              Glob to run ABC metrics over (default: {app,lib}/**/*.rb)
+            --abc-max VALUE              Ignore methods under this complexity (default: 15)
+            --no-abc                     Disable ABC checking
+
+            --style-glob GLOB            Glob to run style metrics over (default: {app,lib,spec}/**/*.rb)
+            --style-measure VALUE        Max line length (default: 80)
+            --no-style                   Disable style checking
+
+            --doc-glob GLOB              Glob to run documentation checks over (default: {app,lib}/**/*.rb)
+            --no-doc                     Disable documentation checking
+
+            --gte FILE,THRESHOLD         If FILE contains a number, verify it is >= to THRESHOLD.
+
+            --max-violations VALUE       Max allowed violations (default: 0)
+
+            --version                    Show version
+        -h, --help                       Show this message
+
+Set default options into a `.cane` file:
+
+    > cat .cane
+    --no-doc
+    --abc-glob **/*.rb
+    > cane
+
+It works just like this:
+
+    > cane --no-doc --abc-glob '**/*.rb'
+
+## Integrating with Rake
+
+    begin
+      require 'cane/rake_task'
+
+      desc "Run cane to check quality metrics"
+      Cane::RakeTask.new(:quality) do |cane|
+        cane.abc_max = 10
+        cane.add_threshold 'coverage/covered_percent', :>=, 99
+        cane.no_style = true
+      end
+
+      task :default => :quality
+    rescue LoadError
+      warn "cane not available, quality task not provided."
+    end
+
+Rescuing `LoadError` is a good idea, since `rake -T` failing is totally
+frustrating.
+
+## Adding to a legacy project
+
+Cane can be configured to still pass in the presence of a set number of
+violations using the `--max-violations` option. This is ideal for retrofitting
+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.
+
+## Integrating with SimpleCov
+
+Any value in a file can be used as a threshold:
+
+    > echo "89" > coverage/covered_percent
+    > cane --gte 'coverage/covered_percent,90'
+
+    Quality threshold crossed
+
+      coverage/covered_percent is 89, should be >= 90
+
+You can use a `SimpleCov` formatter to create the required file:
+
+    class SimpleCov::Formatter::QualityFormatter
+      def format(result)
+        SimpleCov::Formatter::HTMLFormatter.new.format(result)
+        File.open("coverage/covered_percent", "w") do |f|
+          f.puts result.source_files.covered_percent.to_f
+        end
+      end
+    end
+
+    SimpleCov.formatter = SimpleCov::Formatter::QualityFormatter
+
+## Compatibility
+
+Requires MRI 1.9, since it depends on the `ripper` library to calculate
+complexity metrics. This only applies to the Ruby used to run Cane, not the
+project it is being run against. In other words, you can run Cane against your
+1.8 project.
+
+## Support
+
+[Ask questions on Stack
+Overflow](http://stackoverflow.com/questions/ask?tags=ruby+cane). We keep an
+eye on new cane questions.
+
+## Contributing
+
+Fork and patch! Before any changes are merged to master, we need you to sign an
+[Individual Contributor
+Agreement](https://spreadsheets.google.com/a/squareup.com/spreadsheet/viewform?formkey=dDViT2xzUHAwRkI3X3k5Z0lQM091OGc6MQ&ndplr=1)
+(Google Form).

data/bin/cane

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'cane/cli'
+
+result = Cane::CLI.run(ARGV)
+
+exit(1) unless result

data/cane.gemspec

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/cane/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Xavier Shay, Mike Emery"]
+  gem.email         = ["xavier@squareup.com, mike@sparqcode.com"]
+  gem.description   =
+    %q{Fails your build if code quality thresholds are not met}
+  gem.summary       = %q{
+    Fails your build if code quality thresholds are not met. Provides
+    complexity and style checkers built-in, and allows integration with with
+    custom quality metrics.  SPARQCode changed it so that instead of ABC checks it does cyclomatic complexity.
+  }
+  gem.homepage      = "http://github.com/square/cane"
+
+  gem.files         = Dir.glob("{spec,lib}/**/*.rb") + %w(
+                        README.md
+                        HISTORY.md
+                        LICENSE
+                        cane.gemspec
+                      )
+  gem.test_files    = Dir.glob("spec/**/*.rb")
+  gem.name          = "sparqcode_cane"
+  gem.require_paths = ["lib"]
+  gem.bindir        = "bin"
+  gem.executables  << "cane"
+  gem.version       = Cane::VERSION
+  gem.has_rdoc      = false
+  gem.add_development_dependency 'rspec', '~> 2.0'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'simplecov'
+end

data/lib/cane.rb

@@ -0,0 +1,49 @@
+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
+  end
+  module_function :run
+
+  # Orchestrates the running of checks per the provided configuration, and
+  # 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)
+      @opts = opts
+    end
+
+    def run
+      outputter.print ViolationFormatter.new(violations)
+
+      violations.length <= opts.fetch(:max_violations)
+    end
+
+    protected
+
+    attr_reader :opts
+
+    def violations
+      @violations ||= CHECKERS.
+        select { |key, _| opts.has_key?(key) }.
+        map { |key, check| check.new(opts.fetch(key)).violations }.
+        flatten
+    end
+
+    def outputter
+      opts.fetch(:out, $stdout)
+    end
+  end
+end

data/lib/cane/abc_check.rb

@@ -0,0 +1,138 @@
+require 'ripper'
+
+require 'cane/abc_max_violation'
+require 'cane/syntax_violation'
+
+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 violations
+      order file_names.map { |file_name|
+        find_violations(file_name)
+      }.flatten
+    end
+
+    protected
+
+    def find_violations(file_name)
+      ast = Ripper::SexpBuilder.new(File.open(file_name, 'r:utf-8').read).parse
+      case ast
+      when nil
+        InvalidAst.new(file_name)
+      else
+        RubyAst.new(file_name, max_allowed_complexity, ast)
+      end.violations
+    end
+
+    # Null object for when the file cannot be parsed.
+    class InvalidAst < Struct.new(:file_name)
+      def violations
+        [SyntaxViolation.new(file_name)]
+      end
+    end
+
+    # Wrapper object around sexps returned from ripper.
+    class RubyAst < Struct.new(:file_name, :max_allowed_complexity, :sexps)
+      def violations
+        process_ast(sexps).
+          select { |nesting, complexity| complexity > max_allowed_complexity }.
+          map { |x| AbcMaxViolation.new(file_name, x.first, x.last) }
+      end
+
+      protected
+
+      # 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)]
+          complexity[nesting.join(" > ")] = calculate_cyclomatic(node)
+        elsif container_nodes.include?(node[0])
+          parent  = node[1][-1][1]
+          nesting = nesting + [parent]
+        end
+
+        if node.is_a? Array
+          node[1..-1].each { |n| process_ast(n, complexity, nesting) if n }
+        end
+        complexity
+      end
+
+      def calculate_cyclomatic(method_node)
+        cyclomatic = real_cyclomatic(method_node)
+        cyclomatic.size + 1
+      end
+      
+      CONDITIONAL_NODES = [:if, :else, :elsif, :'||', :'&&', 'each', :rescue, :when]
+      
+      def real_cyclomatic(node)        
+        relevant_nodes = []
+        
+        if(node.is_a? Array)
+          node.each do |e|
+            relevant_nodes.concat real_cyclomatic(e)
+          end
+        elsif(CONDITIONAL_NODES.include?(node))
+          relevant_nodes << node
+        end
+        
+        relevant_nodes
+      end
+
+      def calculate_abc(method_node)
+        a = count_nodes(method_node, assignment_nodes)
+        b = count_nodes(method_node, branch_nodes) + 1
+        c = count_nodes(method_node, condition_nodes)
+        abc = Math.sqrt(a**2 + b**2 + c**2).round
+        abc
+      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.
+        node.detect {|x|
+          [:@ident, :@op, :@kw, :@const, :@backtick].include?(x[0])
+        }[1]
+      end
+
+      def count_nodes(node, types)
+        node.flatten.select { |n| types.include?(n) }.length
+      end
+
+      def assignment_nodes
+        [:assign, :opassign]
+      end
+
+      def method_nodes
+        [:def, :defs]
+      end
+
+      def container_nodes
+        [:class, :module]
+      end
+
+      def branch_nodes
+        [:call, :fcall, :brace_block, :do_block]
+      end
+
+      def condition_nodes
+        [:==, :===, :"<>", :"<=", :">=", :"=~", :>, :<, :else, :"<=>"]
+      end
+    end
+
+    def file_names
+      Dir[opts.fetch(:files)]
+    end
+
+    def order(result)
+      result.sort_by(&:sort_index).reverse
+    end
+
+    def max_allowed_complexity
+      opts.fetch(:max)
+    end
+  end
+end

data/lib/cane/abc_max_violation.rb

@@ -0,0 +1,15 @@
+module Cane
+
+  # Value object used by AbcCheck for a method that is too complicated.
+  class AbcMaxViolation < Struct.new(:file_name, :detail, :complexity)
+    def columns
+      [file_name, detail, complexity]
+    end
+
+    def description
+      "Methods exceeded maximum allowed ABC complexity"
+    end
+
+    alias_method :sort_index, :complexity
+  end
+end

data/lib/cane/cli.rb

@@ -0,0 +1,21 @@
+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)
+      else
+        true
+      end
+    end
+    module_function :run
+
+  end
+end