busser 0.9.0 → 0.9.2

data/lib/busser/command/setup.rb

@@ -32,6 +32,10 @@ module Busser
         desc: "Type of binstub file to create (bourne or bat)",
         default: "bourne"
 
+      # Creates the Busser root and the binstub that runs Busser with an
+      # isolated gem environment.
+      #
+      # @return [void]
       def perform
         banner "Setting up Busser"
         create_busser_root
@@ -40,11 +44,15 @@ module Busser
 
       private
 
+      # @return [void]
       def create_busser_root
         info "Creating BUSSER_ROOT in #{root_path}"
         empty_directory(root_path, verbose: false)
       end
 
+      # Writes the binstub, in whichever flavour --type asked for.
+      #
+      # @return [void]
       def generate_busser_binstub
         info "Creating busser binstub"
 
@@ -55,6 +63,9 @@ module Busser
         end
       end
 
+      # Writes a Windows batch binstub.
+      #
+      # @return [void]
       def generate_busser_binstub_for_bat
         binstub = root_path + "bin/busser.bat"
         busser_root = root_path.to_s.gsub("/", "\\")
@@ -79,9 +90,19 @@ module Busser
             SET "GEM_PATH=#{gem_path}"
             SET "GEM_CACHE=#{gem_home}\\cache"
 
-            REM Unset RUBYOPT, we don't want this bleeding into our runtime.
+            REM Keep the calling Ruby environment out of this one. Clearing
+            REM RUBYOPT is no longer enough: RubyGems requires bundler/setup
+            REM whenever BUNDLER_SETUP is set, and bundler then points GEM_HOME
+            REM at the calling project's bundle, undoing the isolation above.
             SET RUBYOPT=
             SET GEMRC=
+            SET RUBYLIB=
+            SET BUNDLER_SETUP=
+            SET BUNDLER_VERSION=
+            SET BUNDLE_BIN_PATH=
+            SET BUNDLE_GEMFILE=
+            SET BUNDLE_LOCKFILE=
+            SET BUNDLE_PATH=
 
             REM Call the actual Busser bin with our arguments
             "#{ruby_bin}" "#{gem_bindir}\\busser" %*
@@ -95,6 +116,9 @@ module Busser
         end
       end
 
+      # Writes a Bourne shell binstub, executable.
+      #
+      # @return [void]
       def generate_busser_binstub_for_bourne
         binstub = root_path + "bin/busser"
 
@@ -120,8 +144,12 @@ module Busser
             GEM_PATH="#{gem_path}"; export GEM_PATH
             GEM_CACHE="#{gem_home}/cache"; export GEM_CACHE
 
-            # Unset RUBYOPT, we don't want this bleeding into our runtime.
-            unset RUBYOPT GEMRC
+            # Keep the calling Ruby environment out of this one. Unsetting
+            # RUBYOPT is no longer enough: RubyGems requires bundler/setup
+            # whenever BUNDLER_SETUP is set, and bundler then points GEM_HOME
+            # at the calling project's bundle, undoing the isolation above.
+            unset RUBYOPT GEMRC RUBYLIB BUNDLER_SETUP BUNDLER_VERSION
+            unset BUNDLE_BIN_PATH BUNDLE_GEMFILE BUNDLE_LOCKFILE BUNDLE_PATH
 
             # Call the actual Busser bin with our arguments
             exec "#{ruby_bin}" "#{gem_bindir}/busser" "$@"
@@ -130,6 +158,8 @@ module Busser
         chmod(binstub, 0755, verbose: false)
       end
 
+      # @return [String] path to the Ruby that is running Busser, in the path
+      #   style the target binstub needs
       def ruby_bin
         result = if (bindir = RbConfig::CONFIG["bindir"])
                    File.join(bindir, "ruby")
@@ -140,18 +170,22 @@ module Busser
         result
       end
 
+      # @return [String] the isolated gem home the binstub exports
       def gem_home
         Gem.paths.home.dup.tap { |p| p.gsub!("/", "\\") if bat? }
       end
 
+      # @return [String] the gem path the binstub exports
       def gem_path
         Gem.paths.path.join(":").dup.tap { |p| p.gsub!("/", "\\") if bat? }
       end
 
+      # @return [String] directory holding the real busser executable
       def gem_bindir
         Gem.bindir.dup.tap { |p| p.gsub!("/", "\\") if bat? }
       end
 
+      # @return [Boolean] true when generating a Windows batch binstub
       def bat?
         options[:type] == "bat"
       end

data/lib/busser/command/suite_cleanup.rb

@@ -28,6 +28,9 @@ module Busser
     #
     class SuiteCleanup < Busser::Thor::BaseGroup
 
+      # Removes the suites directory and everything in it.
+      #
+      # @return [void]
       def cleanup
         if suite_path.directory?
           Pathname.glob(suite_path + "*").each do |dir|

data/lib/busser/command/suite_path.rb

@@ -29,6 +29,9 @@ module Busser
 
       argument :suite_name, required: false
 
+      # Prints where suites live, or where one named suite lives.
+      #
+      # @return [void]
       def path
         say suite_path(suite_name).to_s
       end

data/lib/busser/command/test.rb

@@ -15,11 +15,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "shellwords" unless defined?(Shellwords)
+
 require "busser/thor"
 require "busser/plugin"
 
 module Busser
 
+  # Namespace for Busser's subcommands.
   module Command
 
     # Test command.
@@ -30,6 +33,10 @@ module Busser
 
       argument :plugins, type: :array, required: false
 
+      # Runs each requested plugin's suite, or every installed plugin's suite
+      # when none were named.
+      #
+      # @return [void]
       def perform
         Busser::Plugin.runner_plugins(plugins).each do |runner_path|
           runner = File.basename(runner_path)
@@ -44,26 +51,56 @@ module Busser
         end
       end
 
+      # Builds the command that runs a suite's prepare.sh.
+      #
+      # The path is quoted. It is rooted at BUSSER_ROOT, which the caller
+      # chooses, so an unquoted path containing a space would be split by the
+      # shell and sh would be handed a fragment instead of the script.
+      #
+      # @param script [String, Pathname] path to the prepare.sh
+      # @return [String] the command to run
+      def self.prepare_sh_command(script)
+        "/bin/sh #{Shellwords.escape(script.to_s)}"
+      end
+
       private
 
+      # The dummy runner exists for Busser's own tests, so it only runs when
+      # asked for by name.
+      #
+      # @param runner [String] short plugin name
+      # @return [Boolean] true if this runner should be passed over
       def skip_runner?(runner)
         runner == "dummy" && ! Array(plugins).include?("dummy")
       end
 
+      # Runs whatever preparation the suite ships before its tests.
+      #
+      # @param runner [String] short plugin name
+      # @return [void]
       def prepare_suite(runner)
         run_prepare_sh(runner)
         run_prepare_recipe(runner)
       end
 
+      # Runs the suite's prepare.sh, if it has one.
+      #
+      # @param runner [String] short plugin name
+      # @return [void]
       def run_prepare_sh(runner)
         prepare_sh_script = suite_path(runner).join("prepare.sh")
 
         if prepare_sh_script.exist?
           banner "Preparing #{runner} suite with #{prepare_sh_script}"
-          run!("/bin/sh #{prepare_sh_script}")
+          run!(self.class.prepare_sh_command(prepare_sh_script))
         end
       end
 
+      # Warns if the suite still ships the prepare_recipe.rb that Busser
+      # dropped support for, rather than ignoring it silently.
+      #
+      # @param runner [String] short plugin name
+      # @return [void]
       def run_prepare_recipe(runner)
         prepare_recipe = suite_path(runner).join("prepare_recipe.rb")
 

data/lib/busser/cucumber/hooks.rb

@@ -14,10 +14,19 @@ After do
   end
 end
 
+# Stashes an environment variable so a scenario can change it and have the
+# original put back afterwards.
+#
+# @param key [String] the variable name
+# @return [String, nil] the stashed value
 def backup_envvar(key)
   ENV["_CUKE_#{key}"] = ENV[key]
 end
 
+# Puts back a variable stashed by {backup_envvar}.
+#
+# @param key [String] the variable name
+# @return [String, nil] the restored value
 def restore_envvar(key)
   ENV[key] = ENV.delete("_CUKE_#{key}")
 end

data/lib/busser/helpers.rb

@@ -29,22 +29,41 @@ module Busser
 
     module_function
 
+    # Path to the suites directory, or to one suite inside it.
+    #
+    # @param name [String, nil] a suite name, or nil for the containing
+    #   directory
+    # @return [Pathname] absolute path beneath the Busser root
     def suite_path(name = nil)
       path = root_path + "suites"
       path += name if name
       path.expand_path
     end
 
+    # Path to the vendor directory, or to one vendored product inside it.
+    #
+    # @param product [String, nil] a product name, or nil for the containing
+    #   directory
+    # @return [Pathname] absolute path beneath the Busser root
     def vendor_path(product = nil)
       path = root_path + "vendor"
       path += product if product
       path.expand_path
     end
 
+    # The Busser root, where plugins, suites and vendored products live.
+    #
+    # @return [Pathname] BUSSER_ROOT if set, otherwise /opt/busser
     def root_path
       Pathname.new(ENV["BUSSER_ROOT"] || "/opt/busser")
     end
 
+    # No longer supported. Kept so a plugin still calling it warns rather
+    # than dying with a NoMethodError halfway through a test run.
+    #
+    # @param config [Hash] ignored
+    # @return [void]
+    # @deprecated Shell out or use a Thor action instead.
     def chef_apply(config = {}, &block)
       warn "Apologies, but Busser no longer supports the chef_apply helper," +
         " so the contents of this block will not be executed. Please refactor" +
@@ -52,6 +71,11 @@ module Busser
         " strategy"
     end
 
+    # Installs a gem into the Busser root's gem home.
+    #
+    # @param gem [String] the gem name
+    # @param version [String, nil] a requirement string, or nil for any version
+    # @return [Gem::Specification, nil] the spec that was installed
     def install_gem(gem, version = nil)
       Busser::RubyGems.install_gem(gem, version)
     end

data/lib/busser/plugin.rb

@@ -17,6 +17,7 @@
 
 module Busser
 
+  # Namespace that runner plugins define their classes inside.
   module RunnerPlugin
   end
 
@@ -28,10 +29,17 @@ module Busser
 
     module_function
 
+    # @param plugin_name [String] short plugin name, such as "bash"
+    # @return [String] the path to require for that plugin
     def runner_plugin(plugin_name)
       "busser/runner_plugin/#{plugin_name}"
     end
 
+    # Require paths for the named plugins, or for every installed plugin.
+    #
+    # @param plugin_names [Array<String>, String, nil] plugin names, or nil for
+    #   everything installed
+    # @return [Array<String>] require paths, without duplicates
     def runner_plugins(plugin_names = nil)
       if plugin_names
         Array(plugin_names).map { |plugin| runner_plugin(plugin) }.uniq
@@ -46,33 +54,67 @@ module Busser
     # duplicates made `busser test` run a suite twice and `busser plugin list`
     # print it twice. The path is what gets required, and require resolves to
     # the active version, so collapsing the repeats is safe.
+    # Require paths for every runner plugin installed on this machine.
+    #
+    # @return [Array<String>] require paths, without duplicates
     def all_runner_plugins
       Gem.find_files("busser/runner_plugin/*.rb").map do |file|
         "busser/runner_plugin/#{File.basename(file).sub(/\.rb$/, "")}"
       end.uniq
     end
 
+    # Requires a plugin, exiting with a readable message rather than a
+    # backtrace if it cannot be loaded.
+    #
+    # @param plugin_path [String] the path to require
+    # @return [void]
     def require!(plugin_path)
       require plugin_path
     rescue LoadError => e
       Busser::UI.die "Could not load #{plugin_path} (#{e.class}: #{e.message})"
     end
 
+    # @param klass [String, Symbol] a constant name inside
+    #   {Busser::RunnerPlugin}
+    # @return [Class] the runner plugin class
     def runner_class(klass)
       Busser::RunnerPlugin.const_get(klass)
     end
 
+    # Finds the gemspec a plugin was loaded from.
+    #
+    # A plugin being developed locally is not an installed gem, so the local
+    # gemspec is preferred when the plugin resolves inside the working tree.
+    #
+    # @param plugin_path [String] the plugin's require path
+    # @return [Gem::Specification] the spec the plugin belongs to
     def gem_from_path(plugin_path)
-      local_gem_path = "#{File.expand_path(plugin_path, $LOAD_PATH.first)}"
-      local_gemspec = File.join(
-        File.dirname($LOAD_PATH.first), "busser.gemspec"
-      )
+      # Ask RubyGems first. Loading a gemspec *evaluates* it, and these
+      # gemspecs shell out to `git ls-files` to build their file list -- so
+      # asking the working tree first printed "fatal: not a git repository"
+      # into the middle of `busser plugin list` for every installed plugin.
+      # find_by_path answers from the installed specs without running anything.
+      Gem::Specification.find_by_path(plugin_path) ||
+        local_gemspec_for(plugin_path)
+    end
 
-      if ! Dir.glob("#{local_gem_path}#{Gem.suffix_pattern}").empty?
-        Gem::Specification.load(File.expand_path(local_gemspec))
-      else
-        Gem::Specification.find_by_path(plugin_path)
-      end
+    # Falls back to a gemspec in the working tree, which is how a plugin being
+    # developed locally -- and so not installed as a gem -- is resolved.
+    #
+    # @param plugin_path [String] the plugin's require path
+    # @return [Gem::Specification, nil] the spec, or nil if there is no local
+    #   gemspec to read
+    def local_gemspec_for(plugin_path)
+      root = $LOAD_PATH.first
+      return nil if root.nil?
+
+      local_gem_path = File.expand_path(plugin_path, root)
+      return nil if Dir.glob("#{local_gem_path}#{Gem.suffix_pattern}").empty?
+
+      local_gemspec = File.join(File.dirname(root), "busser.gemspec")
+      return nil unless File.exist?(local_gemspec)
+
+      Gem::Specification.load(local_gemspec)
     end
   end
 end

data/lib/busser/rubygems.rb

@@ -27,11 +27,24 @@ module Busser
 
     module_function
 
+    # @param name [String] the gem name
+    # @param version [String, nil] a requirement string, or nil for any version
+    # @return [Boolean] true if a matching gem is already available
     def gem_installed?(name, version)
       version = Gem::Requirement.default unless version
       ! Gem::Dependency.new(name, version).matching_specs.empty?
     end
 
+    # Installs a gem into GEM_HOME.
+    #
+    # RubyGems under bundler points Gem.dir at the bundle, which is not where
+    # Busser plugins belong, so GEM_HOME is applied explicitly before the
+    # install and the freshly installed spec is put on the load path by hand.
+    #
+    # @param gem_name [String] the gem name
+    # @param version [String, nil] a requirement string, or nil for any version
+    # @return [Gem::Specification, nil] the installed spec, or nil if the gem
+    #   was not among those installed
     def install_gem(gem_name, version)
       version = Gem::Requirement.default unless version
 
@@ -54,6 +67,8 @@ module Busser
       spec
     end
 
+    # @return [Hash] options handed to RubyGems' dependency installer, with
+    #   the install directory pinned to GEM_HOME
     def rbg_options
       @rbg_options ||= Gem::DependencyInstaller::DEFAULT_OPTIONS.merge(
         suggest_alternate: false,
@@ -67,6 +82,11 @@ module Busser
       )
     end
 
+    # Runs a block with RubyGems' own progress output suppressed, unless the
+    # user asked for verbose output.
+    #
+    # @yield the block to run quietly
+    # @return [Object] whatever the block returned
     def silence_gem_ui
       interaction = Gem::DefaultUserInteraction.ui
       unless Gem.configuration.really_verbose

data/lib/busser/runner_plugin/dummy.rb

@@ -34,6 +34,9 @@ class Busser::RunnerPlugin::Dummy < Busser::RunnerPlugin::Base
     create_file("#{dummy_path}/foobar.txt", "The Dummy Driver.")
   end
 
+  # Prints a line so Busser's own suite can prove a plugin ran.
+  #
+  # @return [void]
   def test
     banner "[dummy] Running"
     if File.exist?(File.join(suite_path("dummy"), "foobar.txt"))

data/lib/busser/runner_plugin.rb

@@ -27,6 +27,11 @@ module Busser
     #
     class Base < Busser::Thor::BaseGroup
 
+      # Declares work to run once, when Busser installs this plugin -- which
+      # is where a plugin installs the test framework it drives.
+      #
+      # @yield the postinstall body, evaluated on the plugin instance
+      # @return [void]
       def self.postinstall(&block)
         (class << self; self; end).send(:define_method, :run_postinstall) do
           klass = Class.new(Busser::Thor::BaseGroup) do

data/lib/busser/thor.rb

@@ -22,6 +22,7 @@ require "busser/ui"
 
 module Busser
 
+  # Thor base classes preloaded with Busser's helpers and output methods.
   module Thor
 
     # Base class for all Thor subclasses which includes useful mixins.
@@ -33,6 +34,17 @@ module Busser
       include Helpers
       include UI
       include ::Thor::Actions
+
+      # Thor exits 0 when a command fails unless this is true, and warns on
+      # every failure that it is not set. Busser is a test runner: a failure
+      # has to be a non-zero exit or CI reports a red suite as green. Thor 2
+      # makes this the default; setting it now silences the deprecation on
+      # every failing run and pins the behaviour we already rely on.
+      #
+      # @return [true]
+      def self.exit_on_failure?
+        true
+      end
     end
 
     # Base class for all Thor Group subclasses which includes useful mixins.
@@ -44,6 +56,17 @@ module Busser
       include Helpers
       include UI
       include ::Thor::Actions
+
+      # Thor exits 0 when a command fails unless this is true, and warns on
+      # every failure that it is not set. Busser is a test runner: a failure
+      # has to be a non-zero exit or CI reports a red suite as green. Thor 2
+      # makes this the default; setting it now silences the deprecation on
+      # every failing run and pins the behaviour we already rely on.
+      #
+      # @return [true]
+      def self.exit_on_failure?
+        true
+      end
     end
   end
 end

data/lib/busser/ui.rb

@@ -29,30 +29,56 @@ module Busser
 
     # Thor::Shell's delegated methods are not mixed into this module, so
     # provide the two output primitives it relies on.
+    # @param msg [String] text to write to stdout
+    # @return [void]
     def say(msg)
       $stdout.puts(msg)
     end
 
+    # @param msg [String] text to write to stderr
+    # @return [void]
     def error(msg)
       $stderr.puts(msg)
     end
 
+    # Announces a step, at the top level of the output.
+    #
+    # @param msg [String] the message
+    # @return [void]
     def banner(msg)
       say("-----> #{msg}")
     end
 
+    # Reports detail beneath a banner.
+    #
+    # @param msg [String] the message
+    # @return [void]
     def info(msg)
       say("       #{msg}")
     end
 
+    # Reports something the user should notice but which is not fatal.
+    #
+    # @param msg [String] the message
+    # @return [void]
     def warn(msg)
       say(">>>>>> #{msg}")
     end
 
+    # Reports a failure, on stderr.
+    #
+    # @param msg [String] the message
+    # @return [void]
     def fatal(msg)
       error("!!!!!! #{msg}")
     end
 
+    # Runs a shell command, exiting with a diagnosis if it fails.
+    #
+    # @param cmd [String] the command line
+    # @param config [Hash] options passed through to Thor's runner
+    # @return [true] if the command succeeded
+    # @see #handle_command
     def run!(cmd, config = {})
       config = { capture: false, verbose: false }.merge(config)
 
@@ -61,6 +87,13 @@ module Busser
       end
     end
 
+    # Runs a Ruby script with the current interpreter, exiting with a
+    # diagnosis if it fails.
+    #
+    # @param cmd [String] the script and its arguments
+    # @param config [Hash] options passed through to Thor's runner
+    # @return [true] if the script succeeded
+    # @see #handle_command
     def run_ruby_script!(cmd, config = {})
       config = { capture: false, verbose: false }.merge(config)
 
@@ -69,15 +102,37 @@ module Busser
       end
     end
 
+    # Reports a failure and exits.
+    #
+    # @param msg [String] the message
+    # @param exitstatus [Integer] the status to exit with
+    # @return [void] does not return
     def die(msg, exitstatus = 1)
       fatal(msg)
       exit(exitstatus)
     end
 
+    # Wrapped so tests can stub it.
+    #
+    # @return [Process::Status, nil] the status of the last child process
     def status
       $?
     end
 
+    # Runs a block and turns however the child process ended into a readable
+    # message and a matching exit status.
+    #
+    # Three endings are distinguished because they mean different things to
+    # someone reading CI output: a nil status usually means the machine ran out
+    # of memory before the child could report; a signal means something killed
+    # the run, typically the out of memory killer; and an exit code means the
+    # command itself failed.
+    #
+    # @param type [String] what was run, for the message
+    # @param cmd [String] the command line, for the message
+    # @yield runs the command
+    # @return [true] if the command succeeded
+    # @raise [StandardError] re-raised if the block itself raised
     def handle_command(type, cmd)
       begin
         yield
@@ -96,6 +151,14 @@ module Busser
         )
       elsif status.success?
         true
+      elsif status.exitstatus.nil?
+        # A process killed by a signal has no exit status, and Kernel#exit
+        # rejects nil, so reporting it as an exit code raised a TypeError and
+        # took Busser down with a stack trace rather than a diagnosis. Signals
+        # are how the out of memory killer stops a test run, which is the same
+        # situation the nil status branch above was written for.
+        signal = status.termsig
+        die("#{type} [#{cmd}] was terminated by signal #{signal}", 128 + signal)
       else
         code = status.exitstatus
         die("#{type} [#{cmd}] exit code was #{code}", code)

data/lib/busser/version.rb

@@ -16,5 +16,6 @@
 # limitations under the License.
 
 module Busser
-  VERSION = "0.9.0".freeze
+  # Version string for Busser
+  VERSION = "0.9.2".freeze
 end

data/release-please-config.json

@@ -7,7 +7,9 @@
       "changelog-path": "CHANGELOG.md",
       "release-type": "ruby",
       "include-component-in-tag": false,
-      "version-file": "lib/busser/version.rb"
+      "version-file": "lib/busser/version.rb",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": true
     }
   }
 }

data/spec/busser/command/deserialize_spec.rb

@@ -1,4 +1,3 @@
-# -*- encoding: utf-8 -*-
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.