bashcov 0.0.3 → 0.0.4

data/.travis.yml

@@ -1,4 +1,7 @@
 language: ruby
+after_script:
+  - cane
+  - yard stats --list-undoc
 rvm:
   - 1.9.3
   - 2.0.0
@@ -7,4 +10,3 @@ rvm:
 matrix:
   allow_failures:
     - rvm: ruby-head
-    - rvm: rbx-19mode

data/README.md

@@ -2,7 +2,7 @@
 
 [bashcov] is [simplecov] for Bash.
 
-**[Demo](http://infertux.github.com/bashcov/test_app/)**
+Check out the **[demo](http://infertux.github.com/bashcov/test_app/)** - it's worth a thousand words.
 
 ## Installation
 
@@ -37,6 +37,10 @@ After a bit of parsing, it sends results through _simplecov_ which generates an
 
 And of course, you can take the most of _simplecov_ by adding a `.simplecov` file in your project's root (like [this](https://github.com/infertux/bashcov/blob/master/spec/test_app/.simplecov)).
 
+## Todo
+
+- semver
+
 ## License
 
 MIT

data/bashcov.gemspec

@@ -11,6 +11,7 @@ Gem::Specification.new do |gem|
   gem.description   = %q{Code coverage tool for Bash}
   gem.summary       = gem.description
   gem.homepage      = "https://github.com/infertux/bashcov"
+  gem.license       = 'MIT'
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
@@ -24,4 +25,6 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rspec'
   gem.add_development_dependency 'guard-rspec'
   gem.add_development_dependency 'rb-inotify'
+  gem.add_development_dependency 'cane'
+  gem.add_development_dependency 'yard'
 end

data/bin/bashcov

@@ -13,7 +13,7 @@ coverage = runner.result
 
 require 'simplecov'
 
-SimpleCov.command_name Bashcov.link
+SimpleCov.command_name Bashcov.name
 # SimpleCov.filters = [] # TODO make sure default filters are okay
 SimpleCov::Result.new(coverage).format!
 

data/lib/bashcov.rb

@@ -6,23 +6,31 @@ require 'bashcov/line'
 require 'bashcov/runner'
 require 'bashcov/xtrace'
 
+# Bashcov default module
+# @note Keep it short!
 module Bashcov
   class << self
+    # @return [OpenStruct] Bashcov settings
     attr_reader :options
 
+    # Sets default options overriding any existing ones.
+    # @return [void]
     def set_default_options!
       @options ||= OpenStruct.new
       @options.skip_uncovered = false
       @options.mute = false
     end
 
+    # Parses the given CLI arguments and sets +options+.
+    # @param [Array] args list of arguments
+    # @raise [SystemExit] if invalid arguments are given
+    # @return [void]
     def parse_options! args
       OptionParser.new do |opts|
         opts.banner = "Usage: #{opts.program_name} [options] <filename>"
         opts.version = Bashcov::VERSION
 
-        opts.separator ""
-        opts.separator "Specific options:"
+        opts.separator "\nSpecific options:"
 
         opts.on("-s", "--skip-uncovered", "Do not report uncovered files") do |s|
           @options.skip_uncovered = s
@@ -32,8 +40,7 @@ module Bashcov
           @options.mute = m
         end
 
-        opts.separator ""
-        opts.separator "Common options:"
+        opts.separator "\nCommon options:"
 
         opts.on_tail("-h", "--help", "Show this message") do
           abort(opts.help)
@@ -53,20 +60,32 @@ module Bashcov
       end
     end
 
+    # @return [String] The project's root directory
     def root_directory
       Dir.getwd
     end
 
+    # Program name including version for easy consistent output
+    # @return [String]
+    def name
+      "bashcov v#{VERSION}"
+    end
+
+    # Helper to get a pre-filled coverage array for a given file
+    # @todo This is generic and should be moved in some helpers file.
+    # @api private
+    # @param [String] filename The file to cover.
+    # @param [nil, Integer] fill Value to fill the array with.
+    # @return [Array] An array of the size of the given file.
+    # @example
+    #   coverage_array('file.rb') #=> [0, 0, 0] # assuming file.rb has 3 lines
     def coverage_array(filename, fill = Line::UNCOVERED)
       lines = File.readlines(filename).size
       [fill] * lines
     end
-
-    def link
-      %Q|<a href="https://github.com/infertux/bashcov">bashcov</a> v#{VERSION}|
-    end
   end
 end
 
+# Make sure default options are set
 Bashcov.set_default_options!
 

data/lib/bashcov/lexer.rb

@@ -1,10 +1,18 @@
 module Bashcov
+  # Simple lexer which analyzes Bash files in order to get information for
+  # coverage
   class Lexer
+    # @param [String] filename File to analyze
+    # @raise [ArgumentError] if the given +filename+ is invalid.
     def initialize filename
       @filename = File.expand_path(filename)
-      raise "#{@filename} is not a file" unless File.file?(@filename)
+
+      unless File.file?(@filename)
+        raise ArgumentError, "#{@filename} is not a file"
+      end
     end
 
+    # @return [Array] Irrelevant lines
     def irrelevant_lines
       lines = []
       IO.readlines(@filename).each_with_index do |line, lineno|
@@ -17,11 +25,11 @@ module Bashcov
 
     def is_irrevelant? line
       line.strip!
-      return true if line.empty?
-      return true if start_with.any? { |token| line.start_with? token }
-      return true if is.any? { |keyword| line == keyword }
-      return true if line =~ /\A\w+\(\) {/ # function declared like this: "foo() {"
-      false
+
+      line.empty? or
+      start_with.any? { |token| line.start_with? token } or
+      is.any? { |keyword| line == keyword } or
+      line =~ /\A\w+\(\) {/ # function declared like this: "foo() {"
     end
 
     # Lines containing only one of these keywords are irrelevant for coverage

data/lib/bashcov/line.rb

@@ -1,8 +1,12 @@
 module Bashcov
+  # {Line} represents a line of code
   module Line
-    # see http://www.ruby-doc.org/stdlib-1.9.3/libdoc/coverage/rdoc/Coverage.html
-
+    # Uncovered line
+    # @see http://www.ruby-doc.org/stdlib-1.9.3/libdoc/coverage/rdoc/Coverage.html
     UNCOVERED = 0
+
+    # Ignored line
+    # @see http://www.ruby-doc.org/stdlib-1.9.3/libdoc/coverage/rdoc/Coverage.html
     IGNORED = nil
   end
 end

data/lib/bashcov/runner.rb

@@ -1,64 +1,76 @@
 require 'open4'
 
 module Bashcov
+  # Runs a given command capturing output then computes code coverage.
   class Runner
-    attr_reader :stdout, :stderr
+    # @return [Array] +stdout+ from the last run
+    attr_reader :stdout
 
+    # @return [Array] +stderr+ from the last run
+    attr_reader :stderr
+
+    # @param [String] filename Command to run
     def initialize filename
       @filename = File.expand_path(filename)
     end
 
+    # Runs the command capturing +stdout+ and +stderr+.
+    # @note Binds Bashcov +stdin+ to the program executed.
+    # @note Uses two threads to stream +stdout+ and +stderr+ output in
+    #   realtime.
+    # @return [void]
     def run
       setup
 
       Open4::popen4(@command) do |pid, stdin, stdout, stderr|
         stdin = $stdin # bind stdin
 
-        [ # we need threads here to stream output in realtime
+        [
           Thread.new { # stdout
             stdout.each do |line|
-              $stdout.puts line unless Bashcov.options.mute
               @stdout << line
+              $stdout.puts line unless Bashcov.options.mute
             end
           },
           Thread.new { # stderr
             stderr.each do |line|
-              unless Bashcov.options.mute
-                xtrace = Xtrace.new [line]
-                $stderr.puts line if xtrace.xtrace_output.empty?
-              end
               @stderr << line
+              next if Bashcov.options.mute
+              xtrace = Xtrace.new [line]
+              $stderr.puts line if xtrace.xtrace_output.empty?
             end
           }
         ].map(&:join)
       end
     end
 
+    # @return [Hash] Coverage hash of the last run
     def result
-      if Bashcov.options.skip_uncovered
-        files = {}
+      files = if Bashcov.options.skip_uncovered
+        {}
       else
-        files = find_bash_files "#{Bashcov.root_directory}/**/*.sh"
+        find_bash_files "#{Bashcov.root_directory}/**/*.sh"
       end
 
       files = add_coverage_result files
       files = ignore_irrelevant_lines files
     end
 
+    # @param [String] directory Directory to scan
+    # @return [Hash] Coverage hash of Bash files in the given +directory+. All
+    #   files are marked as uncovered.
     def find_bash_files directory
-      files = {}
-
-      # grab all bash files in project root and mark them uncovered
-      Dir[directory].each do |file|
+      Dir[directory].inject({}) do |files, file|
         absolute_path = File.expand_path(file)
         next unless File.file?(absolute_path)
 
-        files[absolute_path] = Bashcov.coverage_array(absolute_path)
+        files.merge!(absolute_path => Bashcov.coverage_array(absolute_path))
       end
-
-      files
     end
 
+    # @param [Hash] files Initial coverage hash
+    # @return [Hash] Given hash including coverage result from {Xtrace}
+    # @see Xtrace
     def add_coverage_result files
       xtraced_files = Xtrace.new(@stderr).files
 
@@ -72,6 +84,9 @@ module Bashcov
       files
     end
 
+    # @param [Hash] files Initial coverage hash
+    # @return [Hash] Given hash ignoring irrelevant lines
+    # @see Lexer
     def ignore_irrelevant_lines files
       files.each do |filename, lines|
         lexer = Lexer.new(filename)

data/lib/bashcov/version.rb

@@ -1,3 +1,4 @@
 module Bashcov
-  VERSION = "0.0.3"
+  # Bashcov version
+  VERSION = "0.0.4"
 end

data/lib/bashcov/xtrace.rb

@@ -1,14 +1,24 @@
 module Bashcov
+  # This class manages +xtrace+ output.
+  #
+  # @see Runner
   class Xtrace
+    # @param [Array] output Array of output lines.
+    # @raise [ArgumentError] if the given +output+ is not an array
     def initialize output
-      raise "#{output} must be an array" unless output.is_a? Array
+      raise ArgumentError, "#{output} must be an array" unless output.is_a? Array
       @lines = output
     end
 
+    # Filters out non-xtrace lines.
+    # @return [Array] xtrace output
     def xtrace_output
       @lines.select { |line| line =~ Xtrace.line_regexp }
     end
 
+    # Parses xtrace output and computes coverage
+    # @raise [RuntimeError] on invalid files
+    # @return [Hash] Hash of executed files with coverage information
     def files
       files = {}
 
@@ -29,6 +39,8 @@ module Bashcov
       files
     end
 
+    # @see http://www.gnu.org/software/bash/manual/bashref.html#index-PS4
+    # @return [String] +PS4+ variable used for xtrace output
     def self.ps4
       # We use a forward slash as delimiter since it's the only forbidden
       # character in filenames on Unix and Windows.

data/spec/bashcov/lexer_spec.rb

@@ -15,6 +15,14 @@ shared_examples "a bash file" do
 end
 
 describe Bashcov::Lexer do
+  describe "#initialize" do
+    it "raises if the file is invalid" do
+      expect {
+        Bashcov::Lexer.new 'inexistent_file.exe'
+      }.to raise_error ArgumentError
+    end
+  end
+
   expected_coverage.keys.each do |filename|
     context filename do
       it_behaves_like "a bash file" do

data/spec/bashcov_spec.rb

@@ -69,9 +69,9 @@ describe Bashcov do
     end
   end
 
-  describe ".link" do
+  describe ".name" do
     it "includes the version" do
-      Bashcov.link.should include Bashcov::VERSION
+      Bashcov.name.should include Bashcov::VERSION
     end
   end
 end

data/spec/support/test_app.rb

@@ -15,7 +15,7 @@ def uncovered_files
 end
 
 def executed_files
-  bash_files - uncovered_files + ["#{scripts}/sourced.txt"]
+  bash_files - uncovered_files + ["#{scripts}/sourced.txt", "#{scripts}/executable"]
 end
 
 def bash_files
@@ -38,6 +38,8 @@ def expected_coverage
     "#{test_app}/scripts/source.sh" => [nil, nil, 1, nil, 2, nil],
     "#{test_app}/scripts/sourced.txt" => [nil, nil, 1, nil],
     "#{test_app}/scripts/stdin.sh" => [nil, nil, 1, 1, 1, nil],
+    "#{test_app}/scripts/multiline.sh" => [nil, nil, 1, 2, 1, 1, 0, nil],
+    "#{test_app}/scripts/executable" => [nil, nil, 1, nil],
     "#{test_app}/test_suite.sh" => [nil, nil, 2, nil, nil, 2, nil]
   }
 end

data/spec/test_app/scripts/executable

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+echo "Although I'm extension-less, I am an executable Bash script"
+

data/spec/test_app/scripts/multiline.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+[ false = true ] || \
+  [[ 42 -eq 1337 ]] || [[ 1 -eq 1 ]] \
+  && true && \
+  echo 'what?' || \
+  echo 'no!'
+

data/spec/test_app/test_suite.sh

@@ -3,5 +3,5 @@
 cd $(dirname $0)
 
 # `date` is sent on stdin for each file
-date | find scripts -name "*.sh" -exec '{}' \;
+date | find scripts -type f -executable -exec '{}' \;
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bashcov
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-14 00:00:00.000000000 Z
+date: 2013-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: simplecov
@@ -107,6 +107,38 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: cane
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Code coverage tool for Bash
 email:
 - cedric@felizard.fr
@@ -123,7 +155,6 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- TODO
 - bashcov.gemspec
 - bin/bashcov
 - lib/bashcov.rb
@@ -144,8 +175,10 @@ files:
 - spec/test_app/never_called.sh
 - spec/test_app/scripts/README.md
 - spec/test_app/scripts/case.sh
+- spec/test_app/scripts/executable
 - spec/test_app/scripts/function.sh
 - spec/test_app/scripts/long_line.sh
+- spec/test_app/scripts/multiline.sh
 - spec/test_app/scripts/nested/simple.sh
 - spec/test_app/scripts/one_liner.sh
 - spec/test_app/scripts/simple.sh
@@ -154,7 +187,8 @@ files:
 - spec/test_app/scripts/stdin.sh
 - spec/test_app/test_suite.sh
 homepage: https://github.com/infertux/bashcov
-licenses: []
+licenses:
+- MIT
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -190,8 +224,10 @@ test_files:
 - spec/test_app/never_called.sh
 - spec/test_app/scripts/README.md
 - spec/test_app/scripts/case.sh
+- spec/test_app/scripts/executable
 - spec/test_app/scripts/function.sh
 - spec/test_app/scripts/long_line.sh
+- spec/test_app/scripts/multiline.sh
 - spec/test_app/scripts/nested/simple.sh
 - spec/test_app/scripts/one_liner.sh
 - spec/test_app/scripts/simple.sh
@@ -199,3 +235,4 @@ test_files:
 - spec/test_app/scripts/sourced.txt
 - spec/test_app/scripts/stdin.sh
 - spec/test_app/test_suite.sh
+has_rdoc: 

data/TODO

@@ -1,3 +0,0 @@
-see if we could implement some features of https://en.wikipedia.org/wiki/Gcov
-tidy up things
-more comprehensive specs