cuprum-cli 0.1.0

data/lib/cuprum/cli/arguments.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+
+module Cuprum::Cli
+  # Namespace for functionality that implements command positional arguments.
+  module Arguments
+    autoload :ClassMethods, 'cuprum/cli/arguments/class_methods'
+
+    # Exception raised when a command receives too many positional arguments.
+    class ExtraArgumentsError < StandardError; end
+
+    # Exception raised when a command receives an invalid value for an argument.
+    class InvalidArgumentError < StandardError; end
+  end
+end

data/lib/cuprum/cli/coercion.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+
+module Cuprum::Cli
+  # Utility for coercing raw string values to other literal types.
+  module Coercion
+    FALSY_VALUES = Set.new(%w[f false n no]).freeze
+    private_constant :FALSY_VALUES
+
+    INTEGER_PATTERN = /\A-?\d+([\d_,]+\d)?\z/i
+    private_constant :INTEGER_PATTERN
+
+    NULLISH_VALUES = Set.new(['', 'nil', 'null']).freeze
+    private_constant :NULLISH_VALUES
+
+    TRUTHY_VALUES = Set.new(%w[t true y yes]).freeze
+    private_constant :TRUTHY_VALUES
+
+    # Exception raised when trying to coerce an invalid value.
+    class CoercionError < StandardError; end
+
+    # Converts the value to a predicted type based on the value format.
+    #
+    # @param value [Object] the value to convert.
+    #
+    # @return [nil, true, false, Integer, String] the coerced value.
+    def self.coerce(value)
+      skip_validation = true
+
+      return coerce_nil(value, skip_validation:)     if coerce_nil?(value)
+      return coerce_boolean(value, skip_validation:) if coerce_boolean?(value)
+      return coerce_integer(value, skip_validation:) if coerce_integer?(value)
+
+      return value if value.is_a?(String)
+
+      value.inspect
+    end
+
+    # @overload coerce_boolean(value)
+    #   Converts the value to true or false.
+    #
+    #   @param value [Object] the value to convert.
+    #
+    #   @return [true, false] the coerced value.
+    #
+    #   @raise [CoercionError] if the value cannot be coerced to either true or
+    #     false.
+    def self.coerce_boolean(value, skip_validation: false)
+      return false if value.nil?
+
+      if !skip_validation && !coerce_boolean?(value)
+        raise CoercionError,
+          "unable to coerce #{value.inspect} to true or false"
+      end
+
+      value = value.downcase
+
+      return false if FALSY_VALUES.include?(value)
+      return true  if TRUTHY_VALUES.include?(value)
+
+      nil
+    end
+
+    # @return [true, false] true if the value can be safely coerced to either
+    #   true or false, otherwise false.
+    def self.coerce_boolean?(value)
+      return true if value.nil?
+      return false unless value.is_a?(String)
+
+      value = value.downcase
+
+      FALSY_VALUES.include?(value) || TRUTHY_VALUES.include?(value)
+    end
+
+    # @overload coerce_integer(value)
+    #   Converts the value to an Integer.
+    #
+    #   @param value [Object] the value to convert.
+    #
+    #   @return [Integer] the coerced value.
+    #
+    #   @raise [CoercionError] if the value cannot be coerced to an Integer.
+    def self.coerce_integer(value, skip_validation: false)
+      if !skip_validation && !coerce_integer?(value)
+        raise CoercionError,
+          "unable to coerce #{value.inspect} to an Integer"
+      end
+
+      value.tr('_,', '').to_i
+    end
+
+    # @return [true, false] true if the value can be safely coerced to an
+    #   Integer, otherwise false.
+    def self.coerce_integer?(value)
+      return false unless value.is_a?(String)
+
+      value = value.downcase
+
+      INTEGER_PATTERN.match?(value)
+    end
+
+    # @overload coerce_nil(value)
+    #   Converts the value to nil.
+    #
+    #   @param value [Object] the value to convert.
+    #
+    #   @return [nil] the coerced value.
+    #
+    #   @raise [CoercionError] if the value cannot be coerced to nil.
+    def self.coerce_nil(value, skip_validation: false)
+      return nil if value.nil?
+
+      if !skip_validation && !coerce_nil?(value)
+        raise CoercionError,
+          "unable to coerce #{value.inspect} to nil"
+      end
+
+      nil
+    end
+
+    # @return [true, false] true if the value can be safely coerced to nil,
+    #   otherwise false.
+    def self.coerce_nil?(value)
+      return true if value.nil?
+      return false unless value.is_a?(String)
+
+      NULLISH_VALUES.include?(value.downcase)
+    end
+  end
+end

data/lib/cuprum/cli/command.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+require 'plumbum'
+
+require 'cuprum/cli'
+
+module Cuprum::Cli
+  # Abstract base class for defining CLI commands.
+  class Command < Cuprum::Command
+    include Plumbum::Consumer
+    prepend Plumbum::Parameters
+    include Cuprum::Cli::Metadata
+    extend  Cuprum::Cli::Arguments::ClassMethods
+    extend  Cuprum::Cli::Options::ClassMethods
+
+    abstract
+
+    provider Cuprum::Cli::Dependencies.provider
+
+    class << self
+      # (see Cuprum::Cli::Arguments::ClassMethods#argument)
+      def argument(argument_name, **)
+        return super unless abstract?
+
+        raise Cuprum::Cli::Metadata::AbstractCommandError,
+          abstract_command_message("define argument :#{argument_name}")
+      end
+
+      # (see Cuprum::Cli::Dependencies::ClassMethods#dependency)
+      def dependency(dependency_name, **)
+        return super unless abstract?
+
+        raise Cuprum::Cli::Metadata::AbstractCommandError,
+          abstract_command_message("add dependency :#{dependency_name}")
+      end
+
+      # (see Cuprum::Cli::Dependencies::ClassMethods#option)
+      def option(option_name, **)
+        return super unless abstract?
+
+        raise Cuprum::Cli::Metadata::AbstractCommandError,
+          abstract_command_message("define option :#{option_name}")
+      end
+    end
+
+    def initialize(**)
+      super()
+
+      @arguments = {}
+      @options   = {}
+    end
+
+    # @overload call(*arguments, **options)
+    #   Resolves the parameters and calls the command.
+    #
+    #   @param arguments [Array] arguments passed to the command.
+    #   @param options [Hash] options passed to the command.
+    #
+    #   @return [Cuprum::Result] the command result.
+    #
+    #   @raise [Cuprum::Cli::Arguments::ExtraArgumentsError] when given too many
+    #     positional arguments.
+    #   @raise [Cuprum::Cli::Arguments::InvalidArgumentError] when given an
+    #     invalid value for an argument.
+    #   @raise [Cuprum::Cli::Options::InvalidOptionError] when given an invalid
+    #     value for an option.
+    #   @raise [Cuprum::Cli::Options::UnknownOptionError] when given a value for
+    #     an undefined option.
+    #
+    # @overload call(resolved_arguments:, resolved_options:)
+    #   Calls the command with the given arguments and options.
+    #
+    #   This variant assumes that the arguments and options have already been
+    #   parsed and validated against the command's expected parameters.
+    #
+    #   @param resolved_arguments [Hash] the arguments passed to the command,
+    #     formatted as an Hash with the matching argument name as key and the
+    #     argument value as the corresponding value.
+    #   @param resolved_options [Hash] the options passed to the command.
+    #
+    #   @return [Cuprum::Result] the command result.
+    def call(*, resolved_arguments: nil, resolved_options: nil, **)
+      @arguments =
+        resolved_arguments || self.class.resolve_arguments(*)
+      @options   =
+        resolved_options   || self.class.resolve_options(**)
+
+      super()
+    end
+
+    private
+
+    attr_reader :arguments
+
+    attr_reader :options
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/cuprum/cli/commands/ci/report.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbox/heritable_data'
+
+require 'cuprum/cli/commands/ci'
+
+module Cuprum::Cli::Commands::Ci
+  # Data class for recording the results of a CI command.
+  Report = SleepingKingStudios::Tools::Toolbox::HeritableData.define( # rubocop:disable Metrics/BlockLength
+    :label,
+    :duration,
+    :error_count,
+    :failure_count,
+    :pending_count,
+    :success_count,
+    :total_count
+  ) do
+    # @param duration [Integer, Float] the duration of the CI step, in
+    #   seconds.
+    # @param error_count [Integer] the number of static errors reported by the
+    #   step.
+    # @param failure_count [Integer] the number of failures reported by the
+    #   step.
+    # @param label [String] a human-readable representation of the step.
+    # @param pending_count [Integer] the number of pending items reported by
+    #   the step.
+    # @param success_count [Integer] the number of successful items reported
+    #   by the step. Defaults to calculated from the total minus the pending
+    #   and failing items.
+    # @param total_count [Integer] the total number of items reported by the
+    #   step.
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      duration:,
+      total_count:,
+      label:         nil,
+      error_count:   0,
+      failure_count: 0,
+      pending_count: 0,
+      success_count: nil,
+      **
+    )
+      success_count ||= total_count - (failure_count + pending_count)
+
+      super
+    end
+
+    # @return [true, false] true if the step reported any errors, otherwise
+    #   false.
+    def errored? = !error_count.zero?
+
+    # @return [true, false] true if the step reported any failing items,
+    #   otherwise false.
+    def failure? = !failure_count.zero?
+
+    # Combines the given report with the current report.
+    #
+    # @param other_report [Cuprum::Cli::Commands::Ci::Report] the given
+    #   report.
+    #
+    # @return [Cuprum::Cli::Commands::Ci::Report] the combined report.
+    def merge(other_report, with_label: nil) # rubocop:disable Metrics/MethodLength
+      tools.assertions.validate_instance_of(
+        other_report,
+        as:       'report',
+        expected: self.class
+      )
+
+      with_label ||= [label, other_report.label].compact.join(' + ')
+      with_label = nil if with_label.empty?
+
+      self.class.new(
+        label: with_label,
+        **merge_properties(other_report, except: :label)
+      )
+    end
+
+    # @return [true, false] true if the step reported any pending items,
+    #   otherwise false.
+    def pending? = !pending_count.zero?
+
+    # @return [true, false] true if the step did not report any errors or
+    #   failing items; otherwise false.
+    def success? = !errored? && !failure?
+
+    # Generates a human-readable summary of the report.
+    def summary
+      summary = "#{total_count} #{tools.string_tools.pluralize(item_name)}"
+      summary << ", #{failure_count} failures"
+      summary << ", #{pending_count} pending" if pending?
+      summary << ", #{error_count} errors"    if errored?
+
+      summary.freeze
+    end
+
+    private
+
+    def item_name = 'item'
+
+    def merge_properties(other, except: []) # rubocop:disable Metrics/MethodLength
+      excepted = Set.new(Array(except))
+
+      self
+        .class
+        .members
+        .reject { |member_name| excepted.include?(member_name) }
+        .to_h do |member_name|
+          [
+            member_name,
+            [
+              public_send(member_name),
+              other.public_send(member_name)
+            ]
+              .compact
+              .reduce(&:+)
+          ]
+        end
+    end
+
+    def tools = SleepingKingStudios::Tools::Toolbelt.instance
+  end
+end

data/lib/cuprum/cli/commands/ci/rspec_command.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require 'cuprum/cli/commands/ci'
+
+module Cuprum::Cli::Commands::Ci
+  # Command for running an RSpec test suite.
+  class RSpecCommand < Cuprum::Cli::Command
+    # Data class for recording the results of an RSpec command.
+    Report = Cuprum::Cli::Commands::Ci::Report.define do
+      private
+
+      def item_name = 'example'
+    end
+
+    dependency :file_system
+    dependency :standard_io
+    dependency :system_command
+
+    include Cuprum::Cli::Dependencies::StandardIo::Helpers
+    include Cuprum::Cli::Options::Quiet
+
+    arguments :file_patterns
+
+    option :color,    type: :boolean, default: true
+    option :coverage, type: :boolean, default: false
+    option :env,      type: :hash,    default: {}
+    option :format,   type: :string,  default: 'progress'
+    option :gemfile
+
+    description 'Runs an RSpec command.'
+
+    full_name 'ci:rspec'
+
+    private
+
+    def collect_stats
+      file_system.with_tempfile do |tempfile|
+        yield tempfile
+
+        file_system
+          .read_file(tempfile)
+          .then { |raw| JSON.parse(raw) }
+          .then { |hsh| hsh['summary'] }
+      end
+    rescue JSON::ParserError => exception
+      failure(json_error(exception.message))
+    end
+
+    def command_arguments(file_path)
+      [
+        *file_patterns,
+        color? ? '--force-color' : '--no-color',
+        '--format=json',
+        "--out=#{file_path}"
+      ]
+    end
+
+    def command_environment
+      env = self.env.dup
+      env[:coverage]         = false unless coverage?
+      env[:bundler_gemfile]  = gemfile if gemfile
+      env
+    end
+
+    def command_options
+      { format: quiet? ? nil : format }
+    end
+
+    def generate_report(data)
+      Report.new(
+        label:         'ci:rspec',
+        duration:      data.fetch('duration'),
+        error_count:   data.fetch('errors_outside_of_examples_count'),
+        failure_count: data.fetch('failure_count'),
+        pending_count: data.fetch('pending_count'),
+        total_count:   data.fetch('example_count')
+      )
+    end
+
+    def json_error(message)
+      message = "unable to parse JSON results - #{message}"
+
+      Cuprum::Error.new(message:)
+    end
+
+    def process
+      json = step do
+        collect_stats { |tempfile| run_command(tempfile) }
+      end
+
+      report = generate_report(json)
+
+      return success(report) unless report.errored? || report.failure?
+
+      build_result(status: :failure, value: report)
+    end
+
+    def run_command(tempfile)
+      arguments   = command_arguments(tempfile.path)
+      environment = command_environment
+      options     = command_options
+
+      system_command.spawn('rspec', arguments:, environment:, options:)
+    end
+  end
+end

data/lib/cuprum/cli/commands/ci/rspec_each_command.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/commands/ci'
+require 'cuprum/cli/commands/ci/rspec_command'
+
+module Cuprum::Cli::Commands::Ci
+  # Command for running each RSpec file in its own process.
+  class RSpecEachCommand < Cuprum::Cli::Command # rubocop:disable Metrics/ClassLength
+    dependency :file_system
+    dependency :standard_io
+
+    include Cuprum::Cli::Dependencies::StandardIo::Helpers
+    include Cuprum::Cli::Options::Quiet
+
+    arguments :file_patterns
+
+    option :color, type: :boolean, default: true
+    option :env,   type: :hash,    default: {}
+    option :gemfile
+
+    description 'Runs each RSpec file in an isolated process.'
+
+    full_name 'ci:rspec_each'
+
+    private
+
+    attr_reader :errored_files
+
+    attr_reader :failing_files
+
+    attr_reader :pending_files
+
+    attr_reader :report
+
+    def aggregate_file_results(filename:, result:) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      if result.value.is_a?(Cuprum::Cli::Commands::Ci::Report)
+        merge_report(result)
+      end
+
+      if result.value&.errored? || result.failure?
+        errored_files << filename
+      elsif result.value&.failure?
+        failing_files << filename
+      elsif result.value&.pending?
+        pending_files << filename
+      end
+    end
+
+    def color(text, color)
+      return text unless color?
+
+      standard_io.color(text, color)
+    end
+
+    def configured_file_patterns
+      patterns = arguments.fetch(:file_patterns, [])
+
+      return patterns unless patterns.empty?
+
+      ['spec/**{,/*/**}/*_spec.rb']
+    end
+
+    def format_status(result)
+      if result.failure? || result.value.errored?
+        color('Errored', 'red')
+      elsif result.value.failure?
+        color('Failing', 'red')
+      elsif result.value.pending?
+        color('Pending', 'yellow')
+      else
+        color('Passing', 'green')
+      end
+    end
+
+    def matching_files
+      return @matching_files if @matching_files
+
+      all_files = Set.new
+
+      configured_file_patterns.each do |pattern|
+        file_system.each_file(pattern) { |filename| all_files << filename }
+      end
+
+      @matching_files = all_files.sort
+    end
+
+    def merge_report(result) = @report = report.merge(result.value)
+
+    def process
+      reset_report
+
+      say "Running #{matching_files.count} spec files...\n"
+      say "\n" unless matching_files.none?
+
+      matching_files.each { |filename| run_file(filename) }
+
+      summarize_report
+
+      report = @report.with(label: 'ci:rspec_each')
+
+      return success(report) unless report.errored? || report.failure?
+
+      build_result(status: :failure, value: report)
+    end
+
+    def reset_report
+      @errored_files = []
+      @failing_files = []
+      @pending_files = []
+      @report        = Cuprum::Cli::Commands::Ci::RSpecCommand::Report.new(
+        duration:    0.0,
+        total_count: 0
+      )
+    end
+
+    def run_file(filename)
+      command  =
+        Cuprum::Cli::Commands::Ci::RSpecCommand.new(file_system:, standard_io:)
+      result   = command.call(filename, env:, gemfile:, quiet: true)
+      filename = trim_filename(filename)
+
+      say "#{format_status(result)} #{filename}"
+
+      aggregate_file_results(filename:, result:)
+
+      result
+    end
+
+    def say_errored
+      return if errored_files.empty?
+
+      say "\nErrored:\n\n"
+
+      errored_files.each do |filename|
+        say color("  #{filename}", 'red')
+      end
+    end
+
+    def say_failures
+      return if failing_files.empty?
+
+      say "\nFailures:\n\n"
+
+      failing_files.each do |filename|
+        say color("  #{filename}", 'red')
+      end
+    end
+
+    def say_pending
+      return if pending_files.empty?
+
+      say "\nPending:\n\n"
+
+      pending_files.each do |filename|
+        say color("  #{filename}", 'yellow')
+      end
+    end
+
+    def say_summary # rubocop:disable Metrics/AbcSize
+      say "\nFinished in #{report.duration.round(2)} seconds"
+
+      summary_color =
+        if report.errored? || report.failure? || errored_files.any?
+          'red'
+        elsif report.pending? || report.total_count.zero?
+          'yellow'
+        else
+          'green'
+        end
+
+      say color(report.summary, summary_color)
+    end
+
+    def summarize_report
+      say_pending
+      say_failures
+      say_errored
+      say_summary
+    end
+
+    def trim_filename(filename)
+      filename.sub(%r{\A#{file_system.root_path}/?}, '')
+    end
+  end
+end

data/lib/cuprum/cli/commands/ci.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/commands'
+
+module Cuprum::Cli::Commands
+  # Namespace for commands used in continuous integration.
+  module Ci
+    autoload :Report,           'cuprum/cli/commands/ci/report'
+    autoload :RSpecCommand,     'cuprum/cli/commands/ci/rspec_command'
+    autoload :RSpecEachCommand, 'cuprum/cli/commands/ci/rspec_each_command'
+  end
+end