bashcov 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a3fa863e6848203b79a712e22697741dbe3f40e8
-  data.tar.gz: 5a145fc486a1d5ddf0bc09db6d0e0cba65e82bb3
+  metadata.gz: f2fc246b18fc2cbae42869d11c95270f5a5343b4
+  data.tar.gz: a82eae685fd50447bc27e5fe73eff1ff48513f1d
 SHA512:
-  metadata.gz: 3d6dec21c6e9619988ebbc8b811a87fbbcdbc5b73d07405f7ba50e281e81ea8371e45bca945425acaf433fa4eba673f7f68fd84bb08cba7c546e6d6590952854
-  data.tar.gz: 34257113bfc309bb1c7e374c2f23170685c0f5ca59c6b718354a7d0f61dca898ed3979f008c199c35b921fe8a12c804d5ef19aeeacf4b3e9d45df2c172c0d12c
+  metadata.gz: 1e417c499432768996d30fac933516aa2baa52ac4087eec92d0a36c74b8a8df74d55331a3548e4c8e1f3cef9c80e65c6f2deac5d7d9d3629fedf518a92dff85e
+  data.tar.gz: e2f657b4097abcc4973ba66d81ec26e00ef29c881d761f0b02f3b5c1f467d3a6d2c0a11075c4c62115859aacfff9ff78e340043cf51ff0d337f2fa77d0d2fcf9

data/CHANGELOG.md

@@ -1,7 +1,20 @@
-## Unreleased ([changes](https://github.com/infertux/bashcov/compare/v1.2.1...master))
+## Unreleased ([changes](https://github.com/infertux/bashcov/compare/v1.3.0...master))
 
   * TBD
 
+## v1.3.0, 2016-02-10 ([changes](https://github.com/infertux/bashcov/compare/v1.2.1...v1.3.0))
+
+  * [FEATURE] Upgrade SimpleCov dependency to 0.11
+  * [FEATURE] Add support for Ruby 2.3 and drop 1.9
+  * [FEATURE] Add ability to pass `--bash-path` and `--root` as arguments
+  * [FEATURE] Add basic support for Bash versions prior to 4.1 (no `BASH_XTRACEFD`)
+  * [FEATURE] Handle `pushd` & `popd` commands
+  * [BUGFIX]  Fix potential bug with long paths under Bash 4.2 as it truncates `PS4` to 128 characters
+  * [BUGFIX]  Fail gracefully if a Bash script unsets `LINENO`
+  * [BUGFIX]  Refactor parser to not use subshells in `PS4` as it causes erroneous extra hits as well as being slow (classes `FieldStream` & `Xtrace`)
+              Big kudos to @BaxterStockman for his awesome work on PR #16
+              See https://github.com/infertux/bashcov/#some-gory-details
+
 ## v1.2.1, 2015-05-05 ([changes](https://github.com/infertux/bashcov/compare/v1.2.0...v1.2.1))
 
   * [BUGFIX] Preserve original exit status when exiting Bashcov
@@ -18,8 +31,8 @@
 
 ## v1.0.1, 2013-03-21 ([changes](https://github.com/infertux/bashcov/compare/v1.0.0...v1.0.1))
 
-  * [BUGFIX] Allow to add SimpleCov filters.
-  * [BUGFIX] Lines containing only `elif` should be ignored.
+  * [BUGFIX] Allow to add SimpleCov filters
+  * [BUGFIX] Lines containing only `elif` should be ignored
 
 ## v1.0.0, 2013-03-16 ([changes](https://github.com/infertux/bashcov/compare/v0.0.9...v1.0.0))
 

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 # gem 'simplecov', path: '../simplecov'

data/Guardfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # More info at https://github.com/guard/guard#readme
 
 guard "rspec", cli: "--tag ~speed:slow" do

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2012-2015 Cédric Félizard
+Copyright (c) 2012-2016 Cédric Félizard
 
 MIT License
 

data/README.md

@@ -1,4 +1,10 @@
-# Bashcov [![Build Status](https://secure.travis-ci.org/infertux/bashcov.png?branch=master)](https://travis-ci.org/infertux/bashcov) [![Dependency Status](https://gemnasium.com/infertux/bashcov.png)](https://gemnasium.com/infertux/bashcov) [![Code Climate](https://codeclimate.com/github/infertux/bashcov.png)](https://codeclimate.com/github/infertux/bashcov) [![Coverage Status](https://coveralls.io/repos/infertux/bashcov/badge.png?branch=master)](https://coveralls.io/r/infertux/bashcov) [![Gem Version](http://img.shields.io/gem/v/bashcov.svg)](https://rubygems.org/gems/bashcov)
+# Bashcov
+
+[![Build Status](https://secure.travis-ci.org/infertux/bashcov.png?branch=master)](https://travis-ci.org/infertux/bashcov)
+[![Dependency Status](https://gemnasium.com/infertux/bashcov.png)](https://gemnasium.com/infertux/bashcov)
+[![Code Climate](https://codeclimate.com/github/infertux/bashcov.png)](https://codeclimate.com/github/infertux/bashcov)
+[![Coverage Status](https://coveralls.io/repos/infertux/bashcov/badge.png?branch=master)](https://coveralls.io/r/infertux/bashcov)
+[![Gem Version](https://img.shields.io/gem/v/bashcov.svg)](https://rubygems.org/gems/bashcov)
 
 **Code coverage for Bash**
 
@@ -20,11 +26,12 @@
 [Dependencies]: https://gemnasium.com/infertux/bashcov "Bashcov dependencies on Gemnasium"
 [Bashcov]: https://github.com/infertux/bashcov
 [SimpleCov]: https://github.com/colszowka/simplecov "Bashcov is backed by SimpleCov to generate awesome coverage report"
+[Test app demo]: https://infertux.github.com/bashcov/test_app/ "Coverage for the bundled test application"
 
 You should check out these coverage examples - it's worth a thousand words:
 
-  - [Test app demo](http://infertux.github.com/bashcov/test_app/ "Coverage for the bundled test application")
-  - [RVM demo](http://infertux.github.com/bashcov/rvm/ "Coverage for RVM")
+  - [Test app demo]
+  - [RVM demo](https://infertux.github.com/bashcov/rvm/ "Coverage for RVM")
 
 ## Installation
 
@@ -48,8 +55,56 @@ Open `./coverage/index.html` to browse the coverage report.
 
 ### SimpleCov integration
 
-You can take great advantage 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)).
-See [SimpleCov README](https://github.com/colszowka/simplecov#readme) for more information.
+You can take great advantage 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)).
+See [SimpleCov README](https://github.com/colszowka/simplecov#readme) for more
+information.
+
+### Some gory details
+
+Figuring out where an executing Bash script lives in the file system can be
+surprisingly difficult. Bash offers a fair amount of [introspection into its
+internals](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html),
+but the location of the current script has to be inferred from the limited
+information available through `BASH_SOURCE`, `PWD`, and `OLDPWD` (and
+potentially `DIRSTACK` if you are using `pushd`/`popd`). For this purpose,
+Bashcov puts Bash in debug mode and sets up a `PS4` that expands the values of
+these variables, reading them on each command that Bash executes. But, given
+that:
+
+  * `BASH_SOURCE` is only an absolute path if the script was invoked using an
+    absolute path,
+  * the builtins `cd`, `pushd`, and `popd` alter `PWD` and `OLDPWD`, and
+  * none of these variables are read-only and can therefore be `unset` or
+    otherwise altered,
+
+it can be easy to lose track of where we are.
+
+_"Wait a minute, what about `pwd`, `readlink`, and so on?"_ That would be great,
+except that subshells executed as part of expanding the `PS4` can cause Bash to
+report [extra executions](https://github.com/infertux/bashcov/commit/4130874e30a05b7ab6ea66fb96a19acaa973c178)
+for [certain lines](https://github.com/infertux/bashcov/pull/16). Also,
+subshells are slow as the `PS4` is expanded on each and every command when Bash
+is in debug mode.
+
+To deal with these limitations, Bashcov uses the expedient of maintaining two
+stacks that track changes to `PWD` and `OLDPWD`. To determine the full path to
+the executing script, Bashcov iterates in reverse over the `PWD` stack, testing
+for the first `$PWD/$BASH_SOURCE` combination that refers to an existing file.
+This heuristic is susceptible to false positives -- under certain combinations
+of directory structure, script invocation paths, and working directory changes,
+it may yield a path that doesn't refer to the currently-running script.
+However, it performs well under the various working directory changes performed
+in the [test app demo] and avoids the spurious extra hits caused by using
+subshells in the `PS4`.
+
+One final note on innards: Bash 4.3 fixed a bug in which `PS4` expansion is
+truncated to a maximum of 128 characters. On platforms whose Bash version
+suffers from this bug, Bashcov uses the ASCII record separator character to
+delimit the `PS4` fields, whereas it uses a long random string on Bash 4.3 and
+above. When the field delimiter appears in the path of a script under test or
+in a command the script executes, Bashcov won't correctly parse the `PS4` and
+will abort early with incomplete coverage results.
 
 ## Contributing
 

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 
 require "rspec/core/rake_task"

data/bashcov.gemspec

@@ -1,4 +1,5 @@
-# -*- encoding: utf-8 -*-
+# frozen_string_literal: true
+
 lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "bashcov/version"
@@ -13,12 +14,12 @@ Gem::Specification.new do |gem|
   gem.homepage      = "https://github.com/infertux/bashcov"
   gem.license       = "MIT"
 
-  gem.files         = `git ls-files`.split($/)
+  gem.files         = `git ls-files -z`.split("\x0").reject { |f| f.start_with?(".") || f.match(%r{\A(test|spec|features)/}) }
   gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.add_dependency "simplecov", "~> 0.10.0"
+  gem.add_dependency "simplecov", "~> 0.11"
 
   gem.add_development_dependency "rake"
   gem.add_development_dependency "rspec", "~> 3"

data/bin/bashcov

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 lib = File.expand_path("../../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
@@ -7,13 +8,13 @@ require "bashcov"
 
 Bashcov.parse_options! ARGV
 
-runner = Bashcov::Runner.new Bashcov.options.command
+runner = Bashcov::Runner.new Bashcov.command
 status = runner.run
 coverage = runner.result
 
 require "simplecov"
 
-SimpleCov.command_name Bashcov.name
+SimpleCov.command_name Bashcov.fullname
 SimpleCov.root Bashcov.root_directory
 SimpleCov::Result.new(coverage).format!
 

data/lib/bashcov/bash_info.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Bashcov
+  # Module exposing information concerning the installed Bash version
+  # @note methods do not cache results because +bash_path+ can change at
+  #   runtime
+  # @note receiver is expected to implement +bash_path+
+  module BashInfo
+    # @return [Array<String>] An array representing the components of
+    #   +BASH_VERSINFO+
+    def bash_versinfo
+      `#{bash_path} -c 'echo "${BASH_VERSINFO[@]}"'`.chomp.split
+    end
+
+    # @return [Boolean] Whether Bash supports +BASH_XTRACEFD+
+    def bash_xtracefd?
+      bash_versinfo[0..1].join.to_i >= 41
+    end
+
+    # @param [Integer] length the number of bytes to test; default 128
+    # @return [Boolean] whether Bash supports a +PS4+ of at least a given
+    #   number of bytes
+    # @see https://tiswww.case.edu/php/chet/bash/CHANGES
+    # @note Item +i.+ under the +bash-4.2-release+ to +bash-4.3-alpha+ change
+    #   list notes that version 4.2 truncates +PS4+ if it is greater than 128
+    #   bytes.
+    def truncated_ps4?(length = 128)
+      ps4 = SecureRandom.base64(length)
+      !`PS4=#{ps4} #{bash_path} 2>&1 1>&- -xc 'echo hello'`.start_with?(ps4)
+    end
+  end
+end

data/lib/bashcov/errors.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Bashcov
+  # Signals an error parsing Bash's debugging output.
+  class XtraceError < ::RuntimeError
+    # Will contain the coverages parsed prior to the error
+    attr_reader :files
+
+    # @param [#to_s]  message An error message
+    # @param [Hash]   files   A hash containing coverage information
+    def initialize(message, files)
+      @files = files
+      super(message)
+    end
+  end
+end

data/lib/bashcov/field_stream.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Bashcov
+  # Classes for streaming token-delimited fields
+  class FieldStream
+    attr_accessor :read
+
+    # @param [IO] read an IO object opened for reading
+    def initialize(read = nil)
+      @read = read
+    end
+
+    # A convenience wrapper around +each_line(delimiter)+ that also does
+    # +chomp(delimiter)+ on the yielded line.
+    # @param [String, nil] delimiter the field separator for the stream
+    # @return [void]
+    # @yieldparam [String] field each +chomp+ed line
+    def each_field(delimiter)
+      return enum_for(__method__, delimiter) unless block_given?
+
+      read.each_line(delimiter) do |line|
+        yield line.chomp(delimiter)
+      end
+    end
+
+    # Yields fields extracted from a input stream
+    # @param [String, nil] delimiter   the field separator
+    # @param [Integer]     field_count the number of fields to extract
+    # @param [Regexp]      start_match a +Regexp+ that, when matched against the
+    #   input stream, signifies the beginning of the next series of fields to
+    #   yield
+    # @yieldparam [String] field each field extracted from the stream. If
+    #   +start_match+ is matched with fewer than +field_count+ fields yielded
+    #   since the last match, yields empty strings until +field_count+ is
+    #   reached.
+    def each(delimiter, field_count, start_match)
+      unless block_given?
+        return enum_for(__method__, delimiter, field_count, start_match)
+      end
+
+      # Whether the current field is the start-of-fields match
+      matched_start = nil
+
+      # The number of fields processed since passing the last start-of-fields
+      # match
+      seen_fields = 0
+
+      fields = each_field(delimiter)
+
+      # Close over +field_count+ and +seen_fields+ to yield empty strings to
+      # the caller when we've already hit the next start-of-fields match
+      yield_remaining = -> { (field_count - seen_fields).times { yield "" } }
+
+      # Advance until the first start-of-fields match
+      loop { break if fields.next =~ start_match }
+
+      fields.each do |field|
+        # If the current field is the start-of-fields match...
+        if field =~ start_match
+          # Fill out any remaining (unparseable) fields with empty strings
+          yield_remaining.call
+
+          matched_start = nil
+          seen_fields = 0
+        elsif seen_fields < field_count
+            yield field
+            seen_fields += 1
+        end
+      end
+
+      # One last filling-out of empty fields if we're at the end of the stream
+      yield_remaining.call
+
+      read.close unless read.closed?
+    end
+  end
+end

data/lib/bashcov/lexer.rb

@@ -1,24 +1,30 @@
+# frozen_string_literal: true
+
+require "bashcov/line"
+
 module Bashcov
   # Simple lexer which analyzes Bash files in order to get information for
   # coverage
   class Lexer
     # Lines starting with one of these tokens are irrelevant for coverage
-    IGNORE_START_WITH = %w(# function)
+    IGNORE_START_WITH = %w(# function).freeze
 
     # Lines ending with one of these tokens are irrelevant for coverage
-    IGNORE_END_WITH = %w|(|
+    IGNORE_END_WITH = %w|(|.freeze
 
     # Lines containing only one of these keywords are irrelevant for coverage
-    IGNORE_IS = %w(esac if then else elif fi while do done { } ;;)
+    IGNORE_IS = %w(esac if then else elif fi while do done { } ;;).freeze
 
     # @param [String] filename File to analyze
     # @param [Hash] coverage Coverage with executed lines marked
     # @raise [ArgumentError] if the given +filename+ is invalid.
     def initialize(filename, coverage)
-      @filename = File.expand_path(filename)
+      @filename = filename
       @coverage = coverage
 
-      raise ArgumentError, "#{@filename} is not a file" unless File.file?(@filename)
+      unless File.file?(@filename)
+        raise ArgumentError, "#{@filename} is not a file"
+      end
     end
 
     # Yields uncovered relevant lines.
@@ -27,7 +33,7 @@ module Bashcov
     def uncovered_relevant_lines
       lineno = 0
       File.open(@filename, "rb").each_line do |line|
-        if @coverage[lineno] == Bashcov::Line::IGNORED && revelant?(line)
+        if @coverage[lineno] == Bashcov::Line::IGNORED && relevant?(line)
           yield lineno
         end
         lineno += 1
@@ -36,7 +42,7 @@ module Bashcov
 
   private
 
-    def revelant?(line)
+    def relevant?(line)
       line.strip!
 
       !line.empty? and

data/lib/bashcov/line.rb

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

data/lib/bashcov/runner.rb

@@ -1,3 +1,10 @@
+# frozen_string_literal: true
+
+require "bashcov/errors"
+require "bashcov/field_stream"
+require "bashcov/lexer"
+require "bashcov/xtrace"
+
 module Bashcov
   # Runs a given command with xtrace enabled then computes code coverage.
   class Runner
@@ -10,21 +17,44 @@ module Bashcov
     # @note Binds Bashcov +stdin+ to the program being executed.
     # @return [Process::Status] Status of the executed command
     def run
-      inject_xtrace_flag!
+      # Clear out previous run
+      @result = nil
+
+      field_stream = FieldStream.new
+      @xtrace = Xtrace.new(field_stream)
 
-      @xtrace = Xtrace.new
       fd = @xtrace.file_descriptor
-      options = { :in => :in, fd => fd } # bind FDs to the child process
-      options.merge!(out: "/dev/null", err: "/dev/null") if Bashcov.options.mute
-      env = { "BASH_XTRACEFD" => fd.to_s, "PS4" => Xtrace::PS4 }
+      env = { "PS4" => Xtrace.ps4 }
+      options = { in: :in }
+
+      if Bashcov.options.mute
+        options[:out] = "/dev/null"
+        options[:err] = "/dev/null"
+      end
+
+      run_xtrace(fd, env, options) do
+        command_pid = Process.spawn env, *@command, options # spawn the command
 
-      command_pid = Process.spawn env, @command, options # spawn the command
-      xtrace_thread = Thread.new { @xtrace.read } # start processing the xtrace output
+        begin
+          # start processing the xtrace output
+          xtrace_thread = Thread.new { @xtrace.read }
 
-      Process.wait command_pid
-      @xtrace.close
+          Process.wait command_pid
 
-      @coverage = xtrace_thread.value # wait for the thread to return
+          @xtrace.close
+
+          @coverage = xtrace_thread.value # wait for the thread to return
+        rescue XtraceError => e
+          write_warning <<-WARNING
+            encountered an error parsing Bash's output (error was:
+            #{e.message}). This can occur if your script or its path contains
+            the sequence #{Xtrace.delimiter.inspect}, or if your script unsets
+            LINENO. Aborting early; coverage report will be incomplete.
+          WARNING
+
+          @coverage = e.files
+        end
+      end
 
       $?
     end
@@ -37,48 +67,93 @@ module Bashcov
         expunge_invalid_files!
         mark_relevant_lines!
 
-        @coverage
+        convert_coverage
       end
     end
 
   private
 
+    def write_warning(message)
+      warn format "%s: warning: %s", Bashcov.program_name,
+                  message.gsub(/^\s+/, "").lines.map(&:chomp).join(" ")
+    end
+
+    def run_xtrace(fd, env, options)
+      # Older versions of Bash (< 4.1) don't have the BASH_XTRACEFD variable
+      if Bashcov.bash_xtracefd?
+        options[fd] = fd # bind FDs to the child process
+
+        env["BASH_XTRACEFD"] = fd.to_s
+      else
+        # Send subprocess standard error to @xtrace.file_descriptor
+        options[:err] = fd
+
+        # Don't bother issuing warning if we're silencing output anyway
+        unless Bashcov.mute
+          write_warning <<-WARNING
+            you are using a version of Bash that does not support
+            BASH_XTRACEFD. All xtrace output will print to standard error, and
+            your script's output on standard error will not be printed to the
+            console.
+          WARNING
+        end
+      end
+
+      inject_xtrace_flag! do
+        yield
+      end
+    end
+
     # @note +SHELLOPTS+ must be exported so we use Ruby's {ENV} variable
-    # @return [void]
+    # @yield [void] adds "xtrace" to +SHELLOPTS+ and then runs the provided
+    #   block
+    # @return [Object, ...] the value returned by the calling block
     def inject_xtrace_flag!
-      existing_flags = (ENV["SHELLOPTS"] || "").split(":")
+      existing_flags_s = ENV["SHELLOPTS"]
+      existing_flags = (existing_flags_s || "").split(":")
       ENV["SHELLOPTS"] = (existing_flags | ["xtrace"]).join(":")
+
+      yield
+    ensure
+      ENV["SHELLOPTS"] = existing_flags_s
     end
 
     # Add files which have not been executed at all (i.e. with no coverage)
     # @return [void]
     def find_bash_files!
-      return if Bashcov.options.skip_uncovered
+      return if Bashcov.skip_uncovered
 
-      Dir["#{Bashcov.root_directory}/**/*.sh"].each do |file|
-        @coverage[file] ||= [] # empty coverage array
+      Pathname.glob("#{Bashcov.root_directory}/**/*.sh").each do |filename|
+        @coverage[filename] = [] unless @coverage.include?(filename)
       end
     end
 
     # @return [void]
     def expunge_invalid_files!
-      @coverage.each_key do |file|
-        next if File.file? file
+      @coverage.each_key do |filename|
+        next if filename.file?
 
-        @coverage.delete file
-        warn "Warning: #{file} was executed but has been deleted since then - it won't be reported in coverage."
+        @coverage.delete filename
+        write_warning <<-WARNING
+          #{filename} was executed but has been deleted since then - it won't
+          be reported in coverage.
+        WARNING
       end
     end
 
     # @see Lexer
     # @return [void]
     def mark_relevant_lines!
-      @coverage.each do |filename, coverage|
+      @coverage.each_pair do |filename, coverage|
         lexer = Lexer.new(filename, coverage)
         lexer.uncovered_relevant_lines do |lineno|
           @coverage[filename][lineno] = Bashcov::Line::UNCOVERED
         end
       end
     end
+
+    def convert_coverage
+      Hash[@coverage.map { |filename, coverage| [filename.to_s, coverage] }]
+    end
   end
 end

data/lib/bashcov/version.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 # :nodoc:
 module Bashcov
-  VERSION = "1.2.1".freeze
+  # Current Bashcov version
+  VERSION = "1.3.0"
 end