Update CLI.run to return exit status

* Also add yard docs

lib/mutant/cli.rb

@@ -6,16 +6,32 @@ module Mutant
     # Error raised when CLI argv is inalid
     Error = Class.new(RuntimeError)
 
+    # Run cli with arguments
+    #
+    # @param [Array<String>] arguments
+    #
+    # @return [Fixnum]
+    #   returns exit status
+    #
+    # @api private
+    #
     def self.run(*arguments)
-      Runner.run(new(*arguments).runner_options)
+      error = Runner.run(new(*arguments).runner_options).fail?
+      error ? 1 : 0
     end
 
+    # Return options for runner
+    #
+    # @return [Hash]
+    #
+    # @api private
+    #
     def runner_options
       { 
         :mutation_filter => mutation_filter,
         :matcher         => matcher,
         :reporter        => Reporter::CLI.new($stderr),
-        :killer          => Killer::Rspec::Forking
+        :killer          => Killer::Rspec
       }
     end
     memoize :runner_options
@@ -28,10 +44,26 @@ module Mutant
 
     OPTION_PATTERN = %r(\A-(?:-)?[a-z0-9]+\z).freeze
 
+    # Return option for argument with index
+    #
+    # @param [Fixnum] index
+    #
+    # @return [String]
+    #
+    # @api private
+    #
     def option(index)
       @arguments.fetch(index+1)
     end
 
+    # Initialize CLI 
+    #
+    # @param [Array<String>] arguments
+    #
+    # @return [undefined]
+    #
+    # @api private
+    #
     def initialize(arguments)
       @filters, @matchers = [], []
 
@@ -44,16 +76,37 @@ module Mutant
       end
     end
 
+    # Return current argument
+    #
+    # @return [String]
+    #
+    # @api private
+    #
     def current_argument
       @arguments.fetch(@index)
     end
 
+    # Return current option value
+    #
+    # @return [String]
+    #
+    # @raise [CLI::Error]
+    #   raises error when option is missing
+    #
+    # @api private
+    #
     def current_option_value
       @arguments.fetch(@index+1)
     rescue IndexError
       raise Error,"#{current_argument.inspect} is missing an argument"
     end
 
+    # Process current argument
+    #
+    # @return [undefined]
+    #
+    # @api private
+    #
     def dispatch
       if OPTION_PATTERN.match(current_argument)
         dispatch_option
@@ -62,10 +115,25 @@ module Mutant
       end
     end
 
+    # Move processed argument by amount
+    #
+    # @param [Fixnum] amount
+    #   the amount of arguments to be consumed
+    #
+    # @return [undefined]
+    #
+    # @api private
+    #
     def consume(amount)
       @index += amount
     end
 
+    # Process matcher argument
+    # 
+    # @return [undefined]
+    #
+    # @api private
+    #
     def dispatch_matcher
       argument = current_argument
       matcher = Mutant::Matcher.from_string(argument)
@@ -79,6 +147,12 @@ module Mutant
       consume(1)
     end
 
+    # Process option argument
+    #
+    # @return [Undefined]
+    #
+    # @api private
+    #
     def dispatch_option
       argument = current_argument
       arguments = *OPTIONS.fetch(argument) do
@@ -87,11 +161,28 @@ module Mutant
       send(*arguments)
     end
 
+    # Add mutation filter
+    #
+    # @param [Class<Mutant::Filter>]
+    #
+    # @return [undefined]
+    #
+    # @api private
+    #
     def add_filter(klass)
       @filters << klass.new(current_option_value)
       consume(2)
     end
 
+    # Return matcher
+    #
+    # @return [Mutant::Matcher]
+    #
+    # @raise [CLI::Error]
+    #   raises error when matcher is not given
+    #
+    # @api private
+    #
     def matcher
       if @matchers.empty?
         raise Error, 'No matchers given'
@@ -100,6 +191,12 @@ module Mutant
       Mutant::Matcher::Chain.new(@matchers)
     end
 
+    # Return mutation filter
+    #
+    # @return [Mutant::Matcher]
+    #
+    # @api private
+    #
     def mutation_filter
       if @filters.empty?
         Mutation::Filter::ALL

spec/unit/mutant/cli/class_methods/run_spec.rb

@@ -6,7 +6,7 @@ describe Mutant::CLI, '.run' do
   let(:object)   { described_class                                        }
   let(:argv)     { mock('ARGV')                                           }
   let(:options)  { mock('Options')                                        }
-  let(:runner)   { mock('Runner')                                         }
+  let(:runner)   { mock('Runner', :fail? => failure)                      }
   let(:instance) { mock(described_class.name, :runner_options => options) }
 
   before do 
@@ -14,10 +14,25 @@ describe Mutant::CLI, '.run' do
     Mutant::Runner.stub(:run => runner)
   end
 
-  it { should be(runner) }
+  context 'when runner NOT fails' do
+    let(:failure) { false }
 
-  it 'should run with options' do
-    Mutant::Runner.should_receive(:run).with(options).and_return(runner)
-    should be(runner)
+    it { should be(0) }
+
+    it 'should run with options' do
+      Mutant::Runner.should_receive(:run).with(options).and_return(runner)
+      should be(0)
+    end
+  end
+
+  context 'when runner fails' do
+    let(:failure) { true }
+
+    it { should be(1) }
+
+    it 'should run with options' do
+      Mutant::Runner.should_receive(:run).with(options).and_return(runner)
+      should be(1)
+    end
   end
 end