cane 2.2.3 → 2.3.0

data/HISTORY.md

@@ -1,5 +1,11 @@
 # Cane History
 
+## 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)

data/README.md

@@ -78,7 +78,7 @@ Command-line arguments will override arguments specified in the `.cane` file.
         cane.abc_max = 10
         cane.add_threshold 'coverage/covered_percent', :>=, 99
         cane.no_style = true
-        cane.abc_exclude = %w(Foo::Bar.some_method)
+        cane.abc_exclude = %w(Foo::Bar#some_method)
       end
 
       task :default => :quality
@@ -192,6 +192,18 @@ dealt with. In the background job case:
 * What if it failed 5 days ago and we're only looking at it now?
 * Who cares that this job failed?
 
+### Writing a readme
+
+A good README should include at a minimum:
+
+* Why the project exists.
+* How to get started with development.
+* How to deploy the project (if applicable).
+* Status of the project (spike, active development, stable in production).
+* Compatibility notes (1.8, 1.9, JRuby).
+* Any interesting technical or architectural decisions made on the project
+  (this could be as simple as a to an external design document).
+
 ## Compatibility
 
 Requires MRI 1.9, since it depends on the `ripper` library to calculate

data/lib/cane.rb

@@ -1,58 +1,2 @@
-require 'parallel'
-
-require 'cane/violation_formatter'
-
-module Cane
-  def run(*args)
-    Runner.new(*args).run
-  end
-  module_function :run
-
-  def task_runner(opts)
-    if opts[:parallel]
-      Parallel
-    else
-      SimpleTaskRunner
-    end
-  end
-  module_function :task_runner
-
-  # Mirrors the Parallel gem's interface but does not provide any parralleism.
-  # This is faster for smaller tasks since it doesn't incur any overhead for
-  # creating new processes and communicating between them.
-  class SimpleTaskRunner
-    def self.map(enumerable, &block)
-      enumerable.map(&block)
-    end
-  end
-
-  # 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
-    def initialize(spec)
-      @opts = spec
-      @checks = spec[:checks]
-    end
-
-    def run
-      outputter.print ViolationFormatter.new(violations)
-
-      violations.length <= opts.fetch(:max_violations)
-    end
-
-    protected
-
-    attr_reader :opts, :checks
-
-    def violations
-      @violations ||= checks.
-        map {|check| check.new(opts).violations }.
-        flatten
-    end
-
-    def outputter
-      opts.fetch(:out, $stdout)
-    end
-  end
-end
+require 'cane/cli'
+require 'cane/version'

data/lib/cane/abc_check.rb

@@ -2,6 +2,7 @@ require 'ripper'
 require 'set'
 
 require 'cane/file'
+require 'cane/task_runner'
 
 module Cane
 

data/lib/cane/cli.rb

@@ -1,4 +1,4 @@
-require 'cane'
+require 'cane/runner'
 require 'cane/version'
 
 require 'cane/cli/parser'

data/lib/cane/cli/parser.rb

@@ -106,6 +106,9 @@ BANNER
         add_option %w(--max-violations VALUE),
           "Max allowed violations", default: 0, cast: :to_i
 
+        add_option %w(--json),
+          "Output as JSON", default: false
+
         add_option %w(--parallel),
           "Use all processors. Slower on small projects, faster on large.",
             cast: ->(x) { x }

data/lib/cane/doc_check.rb

@@ -1,4 +1,5 @@
 require 'cane/file'
+require 'cane/task_runner'
 
 module Cane
 
@@ -13,11 +14,12 @@ module Cane
     def self.name; "documentation checking"; end
     def self.options
       {
-        doc_glob: ['Glob to run doc checks over',
-                      default:  '{app,lib}/**/*.rb',
-                      variable: 'GLOB',
-                      clobber:  :no_doc],
-        no_doc:   ['Disable documentation checking', cast: ->(x) { !x }]
+        doc_glob:  ['Glob to run doc checks over',
+                       default:  '{app,lib}/**/*.rb',
+                       variable: 'GLOB',
+                       clobber:  :no_doc],
+        no_readme: ['Disable readme checking', cast: ->(x) { !x }],
+        no_doc:    ['Disable documentation checking', cast: ->(x) { !x }]
       }
     end
 
@@ -29,7 +31,7 @@ module Cane
     def violations
       return [] if opts[:no_doc]
 
-      worker.map(file_names) {|file_name|
+      missing_file_violations + worker.map(file_names) {|file_name|
         find_violations(file_name)
       }.flatten
     end
@@ -50,6 +52,19 @@ module Cane
       end.compact
     end
 
+    def missing_file_violations
+      result = []
+      unless opts[:no_readme]
+        unless ['', '.txt', '.md'].any? {|x| Cane::File.exists?("README#{x}") }
+          result << {
+            description: 'Missing documentation',
+            label:       'No README found'
+          }
+        end
+      end
+      result
+    end
+
     def file_names
       Dir[opts.fetch(:doc_glob)]
     end

data/lib/cane/json_formatter.rb

@@ -0,0 +1,17 @@
+require 'json'
+
+module Cane
+
+  # Computes a machine-readable JSON representation from an array of violations
+  # computed by the checks.
+  class JsonFormatter
+    def initialize(violations)
+      @violations = violations
+    end
+
+    def to_s
+      @violations.to_json
+    end
+  end
+
+end

data/lib/cane/runner.rb

@@ -0,0 +1,49 @@
+require 'parallel'
+
+require 'cane/violation_formatter'
+require 'cane/json_formatter'
+
+module Cane
+  def run(*args)
+    Runner.new(*args).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
+    def initialize(spec)
+      @opts = spec
+      @checks = spec[:checks]
+    end
+
+    def run
+      outputter.print formatter.new(violations)
+
+      violations.length <= opts.fetch(:max_violations)
+    end
+
+    protected
+
+    attr_reader :opts, :checks
+
+    def violations
+      @violations ||= checks.
+        map {|check| check.new(opts).violations }.
+        flatten
+    end
+
+    def outputter
+      opts.fetch(:out, $stdout)
+    end
+
+    def formatter
+      if opts[:json]
+        JsonFormatter
+      else
+        ViolationFormatter
+      end
+    end
+  end
+end

data/lib/cane/style_check.rb

@@ -1,6 +1,7 @@
 require 'set'
 
 require 'cane/file'
+require 'cane/task_runner'
 
 module Cane
 
@@ -27,7 +28,7 @@ module Cane
                          type: Array,
                          default: [],
                          clobber: :no_style],
-        no_style:      ['Disable style checking']
+        no_style:      ['Disable style checking', cast: ->(x) { !x }]
       }
     end
 

data/lib/cane/task_runner.rb

@@ -0,0 +1,19 @@
+module Cane
+  def task_runner(opts)
+    if opts[:parallel]
+      Parallel
+    else
+      SimpleTaskRunner
+    end
+  end
+  module_function :task_runner
+
+  # Mirrors the Parallel gem's interface but does not provide any parralleism.
+  # This is faster for smaller tasks since it doesn't incur any overhead for
+  # creating new processes and communicating between them.
+  class SimpleTaskRunner
+    def self.map(enumerable, &block)
+      enumerable.map(&block)
+    end
+  end
+end

data/lib/cane/version.rb

@@ -1,3 +1,3 @@
 module Cane
-  VERSION = '2.2.3'
+  VERSION = '2.3.0'
 end

data/spec/cane_spec.rb

@@ -3,6 +3,7 @@ require "stringio"
 require 'cane/cli'
 
 require 'cane/rake_task'
+require 'cane/task_runner'
 
 # Acceptance tests
 describe 'The cane application' do

data/spec/doc_check_spec.rb

@@ -53,4 +53,19 @@ class Doc; end
       file_name, 4, "AlsoNoDoc"
     ]
   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.txt").and_return(false)
+
+    violations = check("").violations
+    violations.length.should == 1
+
+    violations[0].values_at(:description, :label).should == [
+      "Missing documentation", "No README found"
+    ]
+  end
 end

data/spec/json_formatter_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+require 'cane/json_formatter'
+
+describe Cane::JsonFormatter do
+  it 'outputs violations as JSON' do
+    violations = [{description: 'Fail', line: 3}]
+    JSON.parse(described_class.new(violations).to_s).should ==
+      [{'description' => 'Fail', 'line' => 3}]
+  end
+end

data/spec/parser_spec.rb

@@ -97,4 +97,14 @@ describe Cane::CLI::Parser do
     output.should include("Usage:")
     result.should_not be
   end
+
+  it 'handles no_readme option' do
+    _, result = run("--no-readme")
+    result[:no_readme].should be
+  end
+
+  it 'handles json option' do
+    _, result = run("--json")
+    result[:json].should be
+  end
 end

data/spec/runner_spec.rb

@@ -1,6 +1,6 @@
 require 'spec_helper'
 
-require 'cane'
+require 'cane/runner'
 
 describe Cane::Runner do
   describe '#run' do
@@ -8,5 +8,17 @@ describe Cane::Runner do
       described_class.new(checks: [], max_violations: 0).run.should be
       described_class.new(checks: [], max_violations: -1).run.should_not be
     end
+
+    it 'returns JSON output' do
+      formatter = fire_replaced_class_double("Cane::JsonFormatter")
+      formatter.should_receive(:new).and_return("JSON")
+      buffer = StringIO.new("")
+
+      described_class.new(
+        out: buffer, checks: [], max_violations: 0, json: true
+      ).run
+
+      buffer.string.should == "JSON"
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cane
 version: !ruby/object:Gem::Version
-  version: 2.2.3
+  version: 2.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-03 00:00:00.000000000 Z
+date: 2012-09-16 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/json_formatter_spec.rb
 - spec/parser_spec.rb
 - spec/rake_task_spec.rb
 - spec/runner_spec.rb
@@ -119,8 +120,11 @@ files:
 - lib/cane/doc_check.rb
 - lib/cane/encoding_aware_iterator.rb
 - lib/cane/file.rb
+- lib/cane/json_formatter.rb
 - lib/cane/rake_task.rb
+- lib/cane/runner.rb
 - lib/cane/style_check.rb
+- lib/cane/task_runner.rb
 - lib/cane/threshold_check.rb
 - lib/cane/version.rb
 - lib/cane/violation_formatter.rb
@@ -161,6 +165,7 @@ test_files:
 - spec/cli_spec.rb
 - spec/doc_check_spec.rb
 - spec/encoding_aware_iterator_spec.rb
+- spec/json_formatter_spec.rb
 - spec/parser_spec.rb
 - spec/rake_task_spec.rb
 - spec/runner_spec.rb