sugarcane 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 584226c2dcce2cb64f8634a831906986f21f92f2
+  data.tar.gz: 6a906ebfd9c1088440dfc76fd2db8ca621bac061
+SHA512:
+  metadata.gz: 40e65acb33a378c9e7f779750dee561d982c6aedeb19a24141313657e53b6a8407ec876b23aa6cafbdc9911087758152f5a04d8ba7aeb129a800ec5e801cc5c3
+  data.tar.gz: 78dfc2e99724f66855473ae69c06923989dbc5266d1daf4819e3ceec99039feb28be21ea170a3d769c57ab6141e0ab71399b018a11f81de7188a9805fec19a0c

data/HISTORY.md

@@ -0,0 +1,126 @@
+# SugarCane History
+
+## 0.0.1 - 6 February 2014
+
+* Feature: Menu that takes you from a violation to the line in a text editor
+* Change: expect .sugarcane or .cane configuration files 
+* Change: old cane functionality with --report
+
+# Cane History
+
+## 2.6.1 - 30 October 2013 (2ea008)
+
+* Feature: Don't require doc for one-line class w/out method.
+* Bugfix: JsonFormatter initializer needs to take an options hash.
+* Doc: Add license definition to gemspec.
+
+## 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.
+
+## 2.5.1 - 26 January 2013 (93819f19)
+
+* Feature: documentation check supports `.mdown` and `.rdoc` extensions.
+* Feature: expanded threshold regex to support `coverage/.last_run.json` from
+  `SimpleCov`.
+* Compat: Ruby 2.0 compatibility.
+
+## 2.5.0 - 17 November 2012 (628cc1e9)
+
+* Feature: `--doc-exclude` option to exclude globs from documentation checks.
+* Feature: `--style-exclude` supports globbing.
+
+## 2.4.0 - 21 October 2012 (46949e77)
+
+* Feature: Rake task can load configuration from a `.cane` file.
+* Feature: Coverage threshold can be specifed in a file.
+* Feature: Provide `--all` option for working with single files.
+* Bugfix: Allow README file to be lowercase.
+
+## 2.3.0 - 16 September 2012 (229252ff)
+
+* Feature: `--json` option for machine-readable output.
+* Feature: absence of a README will cause a failure.
+* Bugfix: `--no-style` option actually works now.
+
+## 2.2.3 - 3 September 2012 (e4fe90ee)
+
+* Bugfix: Allow multiple spaces before class name. (#34)
+* Bugfix: Remove wacky broken conditional in AbcCheck. (#33)
+* Doc: Better guidance on class level comments. (#35)
+
+## 2.2.2 - 29 August 2012 (3a9be454)
+
+* Bugfix: Stricter magic comment regex to avoid false positives (#31)
+
+## 2.2.1 - 26 August 2012 (b5e5a362)
+
+* Bugfix: parallel option can be set in rake tasks
+
+## 2.2.0 - 26 August 2012 (f4198619)
+
+* Gracefully handle ambiguous options like `-abc-max` (#27)
+* Provide the `--parallel` option to use all processors. This will be faster on
+  larger projects, but slower on smaller ones (#28)
+
+## 2.1.0 - 26 August 2012 (2962d8fb)
+
+* Support for user-defined checks (#30)
+
+## 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)
+
+This snippet will convert your YAML exclusions file to the new CLI syntax:
+
+    y = YAML.load(File.read('exclusions.yml'))
+    puts (
+      y.fetch('abc',   []).map {|x| %|--abc-exclude "#{x}"| } +
+      y.fetch('style', []).map {|x| %|--style-exclude "#{x}"| }
+    ).join("\n")
+
+## 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
+  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,235 @@
+[![Build Status](https://travis-ci.org/rlqualls/sugarcane.png?branch=master)](https://travis-ci.org/rlqualls/sugarcane)
+[![Coverage Status](https://coveralls.io/repos/rlqualls/sugarcane/badge.png)](https://coveralls.io/r/rlqualls/sugarcane)
+[![Code Climate](https://codeclimate.com/github/rlqualls/sugarcane.png)](https://codeclimate.com/github/rlqualls/sugarcane)
+
+![sugarcane screenshot](http://i.imgur.com/RP7xDLU.png)
+
+> It's best to get beat with something sweet...
+
+**Sugarcane** is an enhancement of the **cane** code quality tool. It makes various
+minor changes, but most importantly, it closes the gap between the text editor
+and cane.
+
+You can find the original cane project at [square/cane](https://github.com/square/cane)
+
+## Features
+
+  - Go straight from violations to their lines in a text editor
+  - Otherwise does what cane does
+  - Editors supported: sublimetext (untested), vim, gedit, nano
+
+## Controls
+
+  - K,W, UP - up
+  - J,S, DOWN - down
+  - Q,X - quit
+  - O, Enter, Space - open file in text editor at the violation
+
+## Installation
+
+    $ gem install sugarcane
+
+## Installation (development)
+
+    $ git clone https://github.com/rlqualls/sugarcane
+    $ cd sugarcane
+    $ bundle
+    $ rake install
+
+## Usage Examples
+
+To run the default checks on all files in your project, navigate to the 
+project root and run sugarcane
+
+    $ sugarcane
+
+If you just want to run all checks on a specific file:
+
+    $ sugarcane -f README.md
+
+If you want to run checks on files matching a pattern:
+
+    $ sugarcane --abc-glob '{lib,spec}/**/*.rb' --abc-max 15
+
+Sugarcane tries to find an editor in your PATH, choosing sublime then vim
+first if one is available. You can specify a different editor with `--editor`.
+
+    $ sugarcane --editor nano
+    $ sugarcane --editor=gedit
+
+**NOTE**: Right now, navigating to a line number relies on the convention
+of `+<num_lines>` as an argument (sublimetext is included as an exception).
+
+## Not far from the Tree
+
+For original `cane` functionality, add the --report option
+
+    $ sugarcane --report
+
+    Methods exceeded maximum allowed ABC complexity (2):
+
+      lib/sugarcane.rb  Cane#sample    23
+      lib/sugarcane.rb  Cane#sample_2  17
+
+    Lines violated style requirements (2):
+
+      lib/sugarcane.rb:20   Line length >80
+      lib/sugarcane.rb:42   Trailing whitespace
+
+    Class definitions require explanatory comments on preceding line (1):
+      lib/sugarcane:3  SomeClass
+
+## Options
+
+    $ sugarcane --help
+    Usage: sugarcane [options]
+
+    Default options are loaded from a .sugarcane file in the current directory.
+
+    -r, --require FILE               Load a Ruby file containing user-defined checks
+    -c, --check CLASS                Use the given user-defined check
+
+        --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 checks over (default: {app,lib,spec}/**/*.rb)
+        --style-measure VALUE        Max line length (default: 80)
+        --style-exclude GLOB         Exclude file or glob from style checking
+        --no-style                   Disable style checking
+
+        --doc-glob GLOB              Glob to run doc checks over (default: {app,lib}/**/*.rb)
+        --doc-exclude GLOB           Exclude file or glob from documentation checking
+        --no-readme                  Disable readme checking
+        --no-doc                     Disable documentation checking
+
+        --lt FILE,THRESHOLD          Check the number in FILE is < to THRESHOLD (a number or another file name)
+        --lte FILE,THRESHOLD         Check the number in FILE is <= to THRESHOLD (a number or another file name)
+        --eq FILE,THRESHOLD          Check the number in FILE is == to THRESHOLD (a number or another file name)
+        --gte FILE,THRESHOLD         Check the number in FILE is >= to THRESHOLD (a number or another file name)
+        --gt FILE,THRESHOLD          Check the number in FILE is > to THRESHOLD (a number or another file name)
+
+    -f, --all FILE                   Apply all checks to given file
+        --max-violations VALUE       Max allowed violations (default: 0)
+        --editor PROGRAM             Text editor to use
+        --json                       Output as JSON
+        --report                     Original cane output
+        --parallel                   Use all processors. Slower on small projects, faster on large.
+        --color                      Colorize output
+
+    -v, --version                    Show version
+    -h, --help                       Show this message
+
+## Configuration Files
+
+Set default options using a `.cane` or '.sugarcane'. This is easier than telling
+sugarcane what editor you want to use every time.
+
+    $ cat .sugarcane
+    --no-doc
+    --abc-glob **/*.rb
+    --editor gedit
+
+It works exactly the same as specifying the options on the command-line.
+Command-line arguments will override arguments specified in the configuration
+file. Sugarcane will ignore a `.cane` file if it sees a `.sugarcane` file.
+
+## Integrating with Rake
+
+Sugarcane retains the ability to create rake tasks. The tasks will look for
+configuration files the same way running sugarcane normally does. The build
+will fail if the task finds more than `max_violations` violations which is 0
+by default. Keep this in mind if using sugarcane tasks in continuous
+integration.
+
+```ruby
+  require 'sugarcane/rake_task'
+
+  desc "Run sugarcane to check quality metrics"
+  SugarCane::RakeTask.new(:quality)
+
+  task :default => :quality
+end
+```
+
+Instead of using a configuration file, you can specify options in a block.
+Rescuing `LoadError` is a good idea, since `rake -T` failing is totally
+frustrating.
+
+```ruby
+begin
+  require 'sugarcane/rake_task'
+
+  desc "Run sugarcane to check quality metrics"
+  SugarCane::RakeTask.new(:quality) do |cane|
+    cane.abc_max = 10
+    cane.no_style = true
+    cane.max_violations = 3
+    cane.abc_exclude = %w(Foo::Bar#some_method)
+  end
+
+  task :default => :quality
+rescue LoadError
+  warn "sugarcane not available, quality task not provided."
+end
+```
+
+If you have multiple configuration files, you can specify which one to use
+with `SugarCane::RakeTask#canefile=`. For that, the name does not matter.
+
+## Implementing your own checks
+
+Checks must implement:
+
+* A class level `options` method that returns a hash of available options. This
+  will be included in help output if the check is added before `--help`. If
+  your check does not require any configuration, return an empty hash.
+* A one argument constructor, into which will be passed the options specified
+  for your check.
+* A `violations` method that returns an array of violations.
+
+See existing checks for guidance. Create your check in a new file:
+
+```ruby
+# unhappy.rb
+class UnhappyCheck < Struct.new(:opts)
+  def self.options
+    {
+      unhappy_file: ["File to check", default: [nil]]
+    }
+  end
+
+  def violations
+    [
+      description: "Files are unhappy",
+      file:        opts.fetch(:unhappy_file),
+      label:       ":("
+    ]
+  end
+end
+```
+
+Include your check either using command-line options:
+
+    sugarcane -r unhappy.rb --check UnhappyCheck --unhappy-file myfile
+
+Or in your rake task:
+
+```ruby
+require 'unhappy'
+
+SugarCane::RakeTask.new(:quality) do |c|
+  c.use UnhappyCheck, unhappy_file: 'myfile'
+end
+```
+## 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 SugarCane, not the
+project it is being run against. In other words, you can run Cane against your
+1.8 or JRuby project.
+
+## Support
+
+Make a [new github issue](https://github.com/rlqualls/sugarcane/issues/new).

data/bin/sugarcane

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

data/lib/cane.rb

@@ -0,0 +1,4 @@
+require 'ncursesw'
+require 'cane/menu'
+require 'cane/cli'
+require 'cane/version'

data/lib/sugarcane/abc_check.rb

@@ -0,0 +1,216 @@
+require 'ripper'
+require 'set'
+
+require 'sugarcane/file'
+require 'sugarcane/ext/array'
+require 'sugarcane/task_runner'
+
+module SugarCane
+
+  # 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
+      return [] if opts[:no_abc]
+
+      order worker.map(file_names) {|file_name|
+        find_violations(file_name)
+      }.flatten
+    end
+
+    protected
+
+    def find_violations(file_name)
+      ast = Ripper::SexpBuilder.new(SugarCane::File.contents(file_name)).parse
+      case ast
+      when nil
+        ast_type = InvalidAst.new(file_name)
+      else
+        ast_type = RubyAst.new(file_name, max_allowed_complexity,
+                               ast, exclusions)
+      end
+      ast_type.violations
+    end
+
+    # Null object for when the file cannot be parsed.
+    class InvalidAst < Struct.new(:file_name)
+      def violations
+        [{file: file_name, description: "File 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 do
+            |nesting, complexity| complexity[:value] > max_allowed_complexity
+          end.
+          map do |violation|
+          {
+            # Here, a violation is an array, like:
+            # ["Class#method", {:value => xx, :line => xx}]
+            file:        file_name,
+            line:        violation.last[:line],
+            label:       violation.first,
+            value:       violation.last[:value],
+            description: "Methods exceeded maximum allowed ABC complexity",
+            menu_description: "#{violation.first} exceeded maximum "\
+                              "ABC complexity"
+          }
+          end
+      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)]
+          desc = method_description(node, *nesting)
+          unless excluded?(desc)
+            complexity[desc] = {
+              :value => calculate_abc(node),
+              :line => node.line_number
+            }
+          end
+        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 }
+        end
+        complexity
+      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 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.
+        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
+
+      METH_CHARS = { def: '#', defs: '.' }
+
+      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(:abc_glob)]
+    end
+
+    def order(result)
+      result.sort_by {|x| x[:value].to_i }.reverse
+    end
+
+    def max_allowed_complexity
+      opts.fetch(:abc_max)
+    end
+
+    def exclusions
+      opts.fetch(:abc_exclude, []).flatten.to_set
+    end
+
+    def worker
+      SugarCane.task_runner(opts)
+    end
+  end
+end

data/lib/sugarcane/cli/options.rb

@@ -0,0 +1,30 @@
+require 'sugarcane/default_checks'
+
+module SugarCane
+  # Default options for command line interface
+  module CLI
+    def defaults(check)
+      check.options.each_with_object({}) {|(k, v), h|
+        option_opts = v[1] || {}
+        if option_opts[:type] == Array
+          h[k] = []
+        else
+          h[k] = option_opts[:default]
+        end
+      }
+    end
+    module_function :defaults
+
+    def default_options
+      {
+        max_violations:  0,
+        parallel:        false,
+        exclusions_file: nil,
+        checks:          SugarCane.default_checks
+      }.merge(SugarCane.default_checks.inject({}) {|a, check|
+        a.merge(defaults(check))
+      })
+    end
+    module_function :default_options
+  end
+end