cuprum-cli 0.1.0 → 0.2.0

data/lib/cuprum/cli/files/generators/ruby_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/files/generators'
+
+module Cuprum::Cli::Files::Generators
+  # Generator for creating a Ruby source file.
+  class RubyGenerator < Cuprum::Cli::Files::Generator
+    match_file(/\.rb\z/)
+
+    option :parent_class
+
+    option :ruby,  type: :boolean, default: true
+    option :rspec, type: :boolean, default: true, aliases: %i[spec]
+
+    option :ruby_template
+    option :rspec_template
+
+    output '%<file_path>s',
+      key:      :ruby,
+      template: File.join(
+        Cuprum::Cli::Files::Generators::TEMPLATES_PATH,
+        'ruby.rb.erb'
+      )
+
+    output File.join('spec', '%<relative_path>s', '%<short_name>s_spec.rb'),
+      key:      :rspec,
+      template: File.join(
+        Cuprum::Cli::Files::Generators::TEMPLATES_PATH,
+        'rspec.rb.erb'
+      )
+  end
+end

data/lib/cuprum/cli/files/generators.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/files'
+
+module Cuprum::Cli::Files
+  # Namespace for pre-defined file generators.
+  module Generators
+    autoload :BasicGenerator, 'cuprum/cli/files/generators/basic_generator'
+    autoload :RSpecGenerator, 'cuprum/cli/files/generators/rspec_generator'
+    autoload :RubyGenerator,  'cuprum/cli/files/generators/ruby_generator'
+
+    # The path for template files, used when defining generators.
+    TEMPLATES_PATH =
+      File
+      .join(
+        Cuprum::Cli.gem_path,
+        'lib',
+        'cuprum',
+        'cli',
+        'files',
+        'templates'
+      )
+      .freeze
+  end
+end

data/lib/cuprum/cli/files/template.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'cuprum/processing'
+require 'sleeping_king_studios/tools/toolbox/heritable_data'
+
+require 'cuprum/cli/files'
+
+module Cuprum::Cli::Files
+  # Data class representing a file generator template.
+  Template =
+    SleepingKingStudios::Tools::Toolbox::HeritableData.define(:engine) do # rubocop:disable Metrics/BlockLength
+      include Cuprum::Processing
+      include Cuprum::ResultHelpers
+      include Cuprum::Steps
+
+      # @param engine [Symbol] the engine used to generate the template
+      #   contents.
+      def initialize(engine: nil, **)
+        super
+      end
+
+      # (see Cuprum::Processing#call)
+      def call(*args, **kwargs, &)
+        steps { super }
+      end
+
+      private
+
+      def apply_engine(template, **parameters)
+        return template unless engine
+
+        engine_class = Cuprum::Cli::Files::Engines.fetch(engine) do
+          return failure(unknown_engine_error)
+        end
+
+        engine_class.new(template_name:).call(template, **parameters)
+      end
+
+      def process(**parameters)
+        template = step { raw_value }
+
+        apply_engine(template, **parameters)
+      end
+
+      def raw_value
+        error = Cuprum::Errors::CommandNotImplemented.new(command: self)
+
+        failure(error)
+      end
+
+      def template_name = nil
+
+      def unknown_engine_error
+        details = "unknown template engine #{engine.inspect}"
+
+        Cuprum::Cli::Files::Errors::TemplateError.new(
+          details:,
+          message: "unable to render template - #{details}"
+        )
+      end
+    end
+end

data/lib/cuprum/cli/files/templates/basic_template.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/files/templates'
+
+module Cuprum::Cli::Files::Templates
+  # Data class representing a template that returns the input contents.
+  BasicTemplate = Cuprum::Cli::Files::Template.define do
+    private
+
+    def process(contents: nil, **parameters)
+      step { validate_contents(contents) }
+
+      apply_engine(contents, **parameters)
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def validate_contents(contents) # rubocop:disable Metrics/MethodLength
+      validator = tools.assertions.aggregator_class.new
+
+      validator.validate_presence(contents, as: 'contents')
+      validator.validate_instance_of(
+        contents,
+        as:       'contents',
+        expected: String
+      )
+
+      return Cuprum::Result.new if validator.empty?
+
+      error = Cuprum::Errors::InvalidParameters.new(
+        command_class: self.class,
+        failures:      validator.each.to_a
+      )
+      failure(error)
+    end
+  end
+end

data/lib/cuprum/cli/files/templates/file_template.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/files/template'
+require 'cuprum/cli/files/templates'
+
+module Cuprum::Cli::Files::Templates
+  # rubocop:disable Metrics/BlockLength
+
+  # Data class representing a template defined on a file.
+  FileTemplate = Cuprum::Cli::Files::Template.define(:file_path, :file_system) \
+  do
+    class_methods = Module.new do
+      # Converts a raw file path to a template object.
+      #
+      # @param file_path [String] the input file path.
+      #
+      # @return [FileTemplate] the generated template.
+      def build(file_path)
+        engine =
+          case File.extname(file_path)
+          when '.erb' then Cuprum::Cli::Files::Engines::ERB
+          end
+
+        new(engine:, file_path:)
+      end
+    end
+    const_set(:ClassMethods, class_methods)
+
+    def self.included(other)
+      super
+
+      other.extend(const_get(:ClassMethods))
+    end
+
+    # @overload initialize(file_path:, engine: nil)
+    #   @param engine [Symbol] the engine used to generate the template
+    #     contents.
+    #   @param file_path [String] the path to the template file.
+    def initialize(file_path:, engine: nil, file_system: nil, **)
+      file_system ||= Cuprum::Cli::Dependencies.provider.get('file_system')
+
+      super(engine:, file_path:, file_system:, **)
+    end
+
+    private
+
+    def raw_value
+      success(file_system.read_file(file_path))
+    rescue Cuprum::Cli::Dependencies::FileSystem::FileNotFoundError
+      error = Cuprum::Cli::Files::Errors::MissingTemplate.new(
+        message:       'unable to generate file',
+        template_path: file_path
+      )
+      failure(error)
+    end
+
+    def template_name = file_path
+  end
+  # rubocop:enable Metrics/BlockLength
+end

data/lib/cuprum/cli/files/templates/string_template.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/files/template'
+require 'cuprum/cli/files/templates'
+
+module Cuprum::Cli::Files::Templates
+  # Data class representing a string literal template.
+  StringTemplate = Cuprum::Cli::Files::Template.define(:raw_template) do
+    class_methods = Module.new do
+      # Converts a raw template string to a template object.
+      #
+      # @param raw_template [String] the unprocessed template string.
+      #
+      # @return [StringTemplate] the generated template.
+      def build(raw_template) = new(engine: nil, raw_template:)
+    end
+    const_set(:ClassMethods, class_methods)
+
+    def self.included(other)
+      super
+
+      other.extend(const_get(:ClassMethods))
+    end
+
+    private
+
+    def raw_value = raw_template
+  end
+end

data/lib/cuprum/cli/files/templates.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/files'
+
+module Cuprum::Cli::Files
+  # Namespace for template files and implementations.
+  module Templates
+    autoload :BasicTemplate,  'cuprum/cli/files/templates/basic_template'
+    autoload :FileTemplate,   'cuprum/cli/files/templates/file_template'
+    autoload :StringTemplate, 'cuprum/cli/files/templates/string_template'
+
+    class << self
+      # Converts a raw input string to a template object.
+      #
+      # - If the input is a Template, returns the input.
+      # - If the input is a single-line String, generates and returns a
+      #   FileTemplate with the input as the file path.
+      # - If the input is a multi-line String, generates and returns a
+      #   StringTemplate with the input as the raw template value.
+      # - For all other values, raises an ArgumentError.
+      #
+      # @param maybe_template [Cuprum::Cli::Files::Template, String] the
+      #   template or unprocessed template string.
+      #
+      # @return [Cuprum::Cli::Files::Template] the generated template.
+      def resolve(maybe_template)
+        if maybe_template.is_a?(Cuprum::Cli::Files::Template)
+          return maybe_template
+        end
+
+        if maybe_template.is_a?(String)
+          return build_template_from_string(maybe_template)
+        end
+
+        tools.assertions.validate_presence(maybe_template, as: 'template')
+
+        raise ArgumentError, 'template must be a Template or file path'
+      end
+
+      private
+
+      def build_template_from_string(maybe_template)
+        tools.assertions.validate_presence(maybe_template, as: 'template')
+
+        if file_path?(maybe_template)
+          Cuprum::Cli::Files::Templates::FileTemplate.build(maybe_template)
+        else
+          Cuprum::Cli::Files::Templates::StringTemplate.build(maybe_template)
+        end
+      end
+
+      def file_path?(value)
+        !value.include?("\n")
+      end
+
+      def tools = SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/cuprum/cli/files.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+
+module Cuprum::Cli
+  # Namespace for shared functionality for manipulating files.
+  module Files
+    autoload :CreateFile,   'cuprum/cli/files/create_file'
+    autoload :Engines,      'cuprum/cli/files/engines'
+    autoload :Errors,       'cuprum/cli/files/errors'
+    autoload :GenerateFile, 'cuprum/cli/files/generate_file'
+    autoload :Generator,    'cuprum/cli/files/generator'
+    autoload :Generators,   'cuprum/cli/files/generators'
+    autoload :RenderErb,    'cuprum/cli/files/render_erb'
+    autoload :Template,     'cuprum/cli/files/template'
+    autoload :Templates,    'cuprum/cli/files/templates'
+  end
+end

data/lib/cuprum/cli/integrations/async/commands/rspec_each_command.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'async'
+require 'async/semaphore'
+
+require 'cuprum/cli/commands/ci/rspec_each_command'
+require 'cuprum/cli/integrations/async/commands'
+
+module Cuprum::Cli::Integrations::Async::Commands
+  # Command for running each RSpec file in its own process with parallelism.
+  class RSpecEachCommand < Cuprum::Cli::Commands::Ci::RSpecEachCommand
+    description 'Runs each RSpec file in an isolated process.'
+
+    full_name 'ci:rspec_each'
+
+    option :max_jobs,
+      type:    :integer,
+      default: Cuprum::Cli::Integrations::Async.max_concurrent_tasks
+
+    private
+
+    def run_matching_files
+      Sync do
+        semaphore = ::Async::Semaphore.new(8)
+
+        matching_files.each do |filename|
+          semaphore.async { run_file(filename) }
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/cli/integrations/async/commands.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/integrations/async'
+
+module Cuprum::Cli::Integrations::Async
+  # Namespace for commands that rely on the Async integration.
+  module Commands
+    autoload :RSpecEachCommand,
+      'cuprum/cli/integrations/async/commands/rspec_each_command'
+  end
+end

data/lib/cuprum/cli/integrations/async.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/integrations'
+
+module Cuprum::Cli::Integrations
+  # Integration with the Async library.
+  #
+  # @see https://socketry.github.io/async/
+  module Async
+    autoload :Commands, 'cuprum/cli/integrations/async/commands'
+
+    class << self
+      # @return [Integer] The recommended maximum number of concurrent Async
+      #   tasks. This value can be configured by setting an
+      #   ASYNC_CONCURRENT_TASKS environment variable. The default value is 8.
+      def max_concurrent_tasks
+        [ENV.fetch('ASYNC_CONCURRENT_TASKS', '8').to_i, 1].max
+      end
+    end
+  end
+end

data/lib/cuprum/cli/integrations/thor/registry.rb

@@ -7,36 +7,14 @@ require 'cuprum/cli/registry'
 module Cuprum::Cli::Integrations::Thor
   # Registers CLI commands by name and adds as Thor tasks.
   class Registry < Cuprum::Cli::Registry
-    # Registers the command with the registry.
-    #
-    # Also registers a Thor task with compatible parameters and metadata.
-    #
-    # @param command [Class] the command class to register.
-    # @param config [Hash] options for configuring the command.
-    #
-    # @option config arguments [Array] arguments to pass to the command on
-    #   initialization.
-    # @option config description [String] the description for the command.
-    # @option config full_description [String] the full description for the
-    #   command.
-    # @option config full_name [String] the name under which to register the
-    #   command. Defaults to the value of command.full_name.
-    # @option config options [Hash] options to pass to the command on
-    #   initialization.
-    #
-    # @raise [NameError] if a command is already registered with that name.
-    #
-    # @return [self]
-    def register(command, **config)
-      super.tap do
-        name    = config.fetch(:full_name, command.full_name)
-        command = commands[name]
+    private
 
-        Cuprum::Cli::Integrations::Thor::Task::Builder
-          .new(command)
-          .build(full_name: name)
-      end
+    def add_registered_command(command)
+      super
+
+      Cuprum::Cli::Integrations::Thor::Task::Builder
+        .new(command)
+        .build(full_name: command.full_name)
     end
-    alias add register
   end
 end

data/lib/cuprum/cli/integrations/thor/task.rb

@@ -110,6 +110,10 @@ module Cuprum::Cli::Integrations::Thor
 
         return :numeric if NUMERIC_TYPES.include?(type)
 
+        # Thor can't handle heterogenous parameters, but it *can* pass them
+        # through as Strings.
+        return :string  if type == 'object'
+
         type.to_sym
       end
 
@@ -183,9 +187,10 @@ module Cuprum::Cli::Integrations::Thor
           command_class.new(**command_dependencies).call(*args, **opts)
 
         handle_failure(result) if result.failure?
-      rescue Cuprum::Cli::Options::UnknownOptionError,
-             Cuprum::Cli::Arguments::ExtraArgumentsError => exception
-        abort(exception.message)
+      rescue StandardError => exception
+        message = failure_message_for_exception(exception)
+
+        abort(message)
       end
     end
 
@@ -195,11 +200,36 @@ module Cuprum::Cli::Integrations::Thor
 
     def abort(*) = Kernel.abort(*)
 
+    def empty?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def failure_message_for_error(error)
+      if error
+        message = "#{command_class} failed with error #{error.class}"
+
+        message << ": #{error.message}" unless empty?(error.message)
+        message << '.'                  unless message.end_with?('.')
+
+        return message
+      end
+
+      "#{command_class} failed but did not return an error message."
+    end
+
+    def failure_message_for_exception(exception)
+      message = "#{command_class} failed with exception: #{exception.message}"
+      message << " (#{exception.class})"
+
+      exception.backtrace.each do |line|
+        message << "\n\t" << line
+      end
+
+      message
+    end
+
     def handle_failure(result)
-      message =
-        result
-        .error
-        &.then { |err| "#{err.class.name}: #{err.message}" } || false
+      message = failure_message_for_error(result.error)
 
       abort(message)
     end

data/lib/cuprum/cli/metadata.rb

@@ -19,7 +19,7 @@ module Cuprum::Cli
     class AbstractCommandError < StandardError; end
 
     # Class methods to extend when including Metadata.
-    module ClassMethods
+    module ClassMethods # rubocop:disable Metrics/ModuleLength
       # Marks the command as abstract.
       def abstract = @abstract = true
 
@@ -102,7 +102,7 @@ module Cuprum::Cli
       #
       #   @return [String] the set full name.
       def full_name(value = UNDEFINED) # rubocop:disable Metrics/MethodLength
-        return defined_full_name if value == UNDEFINED
+        return @full_name || defined_full_name if value == UNDEFINED
 
         if abstract?
           raise AbstractCommandError, abstract_command_message('set full_name')
@@ -119,6 +119,12 @@ module Cuprum::Cli
         @full_name = value
       end
 
+      # @return [true, false] true if the command defines a custom name;
+      #   otherwise false.
+      def full_name?
+        !@full_name.nil?
+      end
+
       # The namespace for the command.
       #
       # A command's namespace is defined as the part of the full name prior to
@@ -152,7 +158,50 @@ module Cuprum::Cli
       #   short_name will be "do_something".
       #
       # @return [String] the short name for the command.
-      def short_name = full_name&.split(':')&.last
+      def short_name
+        full_name&.split(':')&.last
+      end
+
+      # Sets the description for the command.
+      #
+      # @param value [String] the description to set.
+      #
+      # @return [self]
+      #
+      # @see #description
+      def with_description(value)
+        description(value)
+
+        self
+      end
+
+      # Sets the full description for the command and returns the command.
+      #
+      # @param value [String] the full description to set.
+      #
+      # @return [self]
+      #
+      # @see #full_description
+      def with_full_description(value)
+        full_description(value)
+
+        self
+      end
+
+      # Sets the full name for the command and returns the command.
+      #
+      # The full name must be in snake_case format joined by ":".
+      #
+      # @param value [String] the full name to set.
+      #
+      # @return [self]
+      #
+      # @see #full_name
+      def with_full_name(value)
+        full_name(value)
+
+        self
+      end
 
       protected
 
@@ -182,13 +231,13 @@ module Cuprum::Cli
       end
 
       def defined_full_name
-        return @full_name if @full_name ||= default_name
+        return @defined_full_name if @defined_full_name ||= default_name
 
         return unless superclass.respond_to?(:defined_full_name, true)
 
         return if superclass.name == 'Cuprum::Cli::Command'
 
-        superclass.defined_full_name
+        superclass.full_name
       end
 
       private

data/lib/cuprum/cli/option.rb

@@ -39,9 +39,9 @@ module Cuprum::Cli # rubocop:disable Metrics/ModuleLength
       default:        nil,
       description:    nil,
       parameter_name: nil,
-      required:       false,
+      required:       false, # rubocop:disable Layout/ExtraSpacing
       type:           :string,
-      variadic:       false
+      variadic:       false # rubocop:disable Layout/ExtraSpacing
     )
       name     = name.to_sym
       aliases  = Array(aliases).compact.map { |obj| obj.to_s.tr('_', '-') }
@@ -81,8 +81,8 @@ module Cuprum::Cli # rubocop:disable Metrics/ModuleLength
       value = default_value if blank?(value)
       value = value.to_s    if value.is_a?(Symbol)
 
-      return default_value_for_type if value.nil? && !required?
-      return value                  if valid_option?(value)
+      return default_value_for_type         if value.nil? && !required?
+      return normalize_variadic_keys(value) if valid_option?(value)
 
       raise Cuprum::Cli::Options::InvalidOptionError,
         invalid_option_message(original_value)
@@ -135,6 +135,12 @@ module Cuprum::Cli # rubocop:disable Metrics/ModuleLength
         "received #{value.inspect}"
     end
 
+    def normalize_variadic_keys(value)
+      return value unless variadic?
+
+      value.transform_keys { |key| tools.string_tools.underscore(key).to_sym }
+    end
+
     def tools
       SleepingKingStudios::Tools::Toolbelt.instance
     end

data/lib/cuprum/cli/options/class_methods.rb

@@ -131,7 +131,7 @@ module Cuprum::Cli::Options
     # @raise [Cuprum::Cli::Options::InvalidOptionError] if any value does not
     #   match the expected option type, or any required value is missing.
     def resolve_options(**values)
-      values                  = option_values.merge(values)
+      values                  = option_values.merge(resolve_aliases(values))
       defined_options         = options
       values, unknown_options = resolve_variadic_values(values)
 
@@ -188,6 +188,24 @@ module Cuprum::Cli::Options
       # :nocov:
     end
 
+    def resolve_aliases(values)
+      options.each do |key, option|
+        option.aliases.each do |item|
+          alias_key = item.to_sym
+
+          next unless values.key?(alias_key)
+
+          # Always remove the alias from the options.
+          alias_value = values.delete(alias_key)
+
+          # If the original value is present, it takes precedence.
+          values[key] ||= alias_value
+        end
+      end
+
+      values
+    end
+
     def resolve_variadic_values(values) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       defined_options = options
       unknown_options = values.keys - options.keys