cuprum-cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/files'
+
+module Cuprum::Cli::Files
+  # Namespace for commands that process raw templates into file contents.
+  module Engines
+    class << self
+      # @overload fetch(engine)
+      #   Retrieves the render command for the given engine.
+      #
+      #   @param engine [String] the engine identifier.
+      #
+      #   @return [Cuprum::Command] the render command for the engine.
+      #
+      #   @raise [KeyError] if there is no matching engine.
+      #
+      # @overload fetch(engine, default)
+      #   Retrieves the render command for the given engine.
+      #
+      #   @param engine [String] the engine identifier.
+      #   @param default [Cuprum::Command] the command to return if there is no
+      #     matching engine.
+      #
+      #   @return [Cuprum::Command] the render command for the engine.
+      #
+      # @overload fetch(engine) { |engine| }
+      #   Retrieves the render command for the given engine.
+      #
+      #   If there is no matching engine. calls the block with the given engine.
+      #
+      #   @param engine [String] the engine identifier.
+      #
+      #   @return [Cuprum::Command] the render command for the engine.
+      #
+      #   @yieldparam engine [String] the engine identifier.
+      #
+      #   @yieldreturn [Cuprum::Command] the command to return if there is no
+      #     matching engine.
+      def fetch(engine, default = UNDEFINED, &)
+        return engines.fetch(engine, &) if default == UNDEFINED
+
+        engines.fetch(engine, default)
+      end
+
+      # Registers a render command for the specified engine.
+      #
+      # @param engine [String] the engine identifier.
+      # @param render_command [Cuprum::Command] the render command for the
+      #   engine.
+      #
+      # @return [void]
+      def register(engine, render_command)
+        engines[engine] = render_command
+
+        nil
+      end
+
+      private
+
+      def default_engines
+        { ERB => Cuprum::Cli::Files::Engines::RenderErb }
+      end
+
+      def engines = @engines ||= default_engines
+    end
+
+    autoload :RenderErb, 'cuprum/cli/files/engines/render_erb'
+
+    # Identifier for ERB files.
+    ERB = 'cuprum.cli.files.engines.erb'
+
+    UNDEFINED = SleepingKingStudios::Tools::UNDEFINED
+    private_constant :UNDEFINED
+  end
+end

data/lib/cuprum/cli/{errors/files → files/errors}/file_not_writeable.rb

@@ -2,13 +2,13 @@
 
 require 'cuprum/error'
 
-require 'cuprum/cli/errors/files'
+require 'cuprum/cli/files/errors'
 
-module Cuprum::Cli::Errors::Files
+module Cuprum::Cli::Files::Errors
   # Error returned when attempting to generate a file in an invalid location.
   class FileNotWriteable < Cuprum::Error
     # Short string used to identify the type of error.
-    TYPE = 'cuprum.cli.errors.files.file_not_writeable'
+    TYPE = 'cuprum.cli.files.errors.file_not_writeable'
 
     # @param file_path [String] the path to the expected file.
     # @param message [String] message describing the nature of the error.

data/lib/cuprum/cli/files/errors/generator_error.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/files/errors'
+
+module Cuprum::Cli::Files::Errors
+  # Error returned when an error occurs when calling a generator.
+  class GeneratorError < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.cli.files.errors.generator_error'
+
+    # @param message [String] message describing the nature of the error.
+    # @param details [String] additional information about the error.
+    # @param file_path [String] the file path passed to the generator.
+    # @param options [Hash] additional options passed to the generator.
+    def initialize(message:, details: nil, file_path: nil, options: {}, **)
+      @details   = details
+      @file_path = file_path
+      @options   = options
+
+      super
+    end
+
+    # @return [String] additional information about the error.
+    attr_reader :details
+
+    # @return [String] the file path passed to the generator.
+    attr_reader :file_path
+
+    # @return [Hash] additional options passed to the generator.
+    attr_reader :options
+
+    private
+
+    def as_json_data
+      options = self.options.empty? ? nil : self.options.transform_keys(&:to_s)
+
+      super
+        .merge(
+          'details'   => details,
+          'file_path' => file_path,
+          'options'   => options
+        )
+        .compact
+    end
+  end
+end

data/lib/cuprum/cli/{errors/files → files/errors}/missing_parameter.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require 'cuprum/cli/errors/files'
-require 'cuprum/cli/errors/files/template_error'
+require 'cuprum/cli/files/errors'
+require 'cuprum/cli/files/errors/template_error'
 
-module Cuprum::Cli::Errors::Files
+module Cuprum::Cli::Files::Errors
   # Error returned when a required parameter is missing when rendering content.
-  class MissingParameter < Cuprum::Cli::Errors::Files::TemplateError
+  class MissingParameter < Cuprum::Cli::Files::Errors::TemplateError
     # Short string used to identify the type of error.
-    TYPE = 'cuprum.cli.errors.files.missing_parameter'
+    TYPE = 'cuprum.cli.files.errors.missing_parameter'
 
     # @param parameter_name [String, Symbol] the name of the missing parameter.
     # @param details [String] additional information about the error.

data/lib/cuprum/cli/{errors/files → files/errors}/missing_template.rb

@@ -2,13 +2,13 @@
 
 require 'cuprum/error'
 
-require 'cuprum/cli/errors/files'
+require 'cuprum/cli/files/errors'
 
-module Cuprum::Cli::Errors::Files
+module Cuprum::Cli::Files::Errors
   # Error returned when unable to load a template.
   class MissingTemplate < Cuprum::Error
     # Short string used to identify the type of error.
-    TYPE = 'cuprum.cli.errors.files.missing_template'
+    TYPE = 'cuprum.cli.files.errors.missing_template'
 
     # @param template_path [String] the expected template path.
     # @param message [String] an optional message to display.

data/lib/cuprum/cli/{errors/files → files/errors}/template_error.rb

@@ -2,13 +2,13 @@
 
 require 'cuprum/error'
 
-require 'cuprum/cli/errors/files'
+require 'cuprum/cli/files/errors'
 
-module Cuprum::Cli::Errors::Files
+module Cuprum::Cli::Files::Errors
   # Error returned when an error occurs when generating templated content.
   class TemplateError < Cuprum::Error
     # Short string used to identify the type of error.
-    TYPE = 'cuprum.cli.errors.files.template_error'
+    TYPE = 'cuprum.cli.files.errors.template_error'
 
     # @param message [String] message describing the nature of the error.
     # @param details [String] additional information about the error.

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/files'
+
+module Cuprum::Cli::Files
+  # Namespace for errors returned when creating or managing files.
+  module Errors
+    autoload :FileNotWriteable,
+      'cuprum/cli/files/errors/file_not_writeable'
+    autoload :GeneratorError,
+      'cuprum/cli/files/errors/generator_error'
+    autoload :MissingParameter,
+      'cuprum/cli/files/errors/missing_parameter'
+    autoload :MissingTemplate,
+      'cuprum/cli/files/errors/missing_template'
+    autoload :TemplateError,
+      'cuprum/cli/files/errors/template_error'
+  end
+end

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

@@ -0,0 +1,431 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+require 'plumbum'
+
+require 'cuprum/cli/files'
+
+module Cuprum::Cli::Files
+  # Command for generating templated files.
+  class Generator < Cuprum::Command # rubocop:disable Metrics/ClassLength
+    include Plumbum::Consumer
+    prepend Plumbum::Parameters
+    include Cuprum::Cli::Dependencies::StandardIo::Helpers
+    extend  Cuprum::Cli::Options::ClassMethods
+    include Cuprum::Cli::Options::Quiet
+    include Cuprum::Cli::Options::Verbose
+
+    # Raised when performing a protected operation on an abstract Generator.
+    class AbstractGeneratorError < StandardError; end
+
+    # Raised when performing a protected operation on an abstract Generator.
+    class OutputAlreadyExistsError < KeyError; end
+
+    # Data class representing a configured output file.
+    Output = Data.define(:key, :path, :template)
+
+    class << self
+      # Marks the generator as abstract.
+      def abstract = @abstract = true
+
+      # @return [true, false] true if the generator is abstract and should not
+      #   be assigned matchers or outputs; otherwise false.
+      def abstract? = @abstract.nil? ? false : @abstract
+
+      # @overload match_file(pattern)
+      #   Registers the pattern as a valid match for the generator.
+      #
+      #   The registered matches are checked when the generator checks whether a
+      #   file path can be generated by the generator.
+      #
+      #   - If the given pattern is a regular expression, the generator will
+      #     match the pattern against the file path.
+      #   - If the pattern is a string, the generator will check if the file
+      #     path ends with the pattern string.
+      #
+      #   @param pattern [Regexp, String] the pattern to register.
+      #
+      #   @return [void]
+      #
+      # @overload match_file(&block)
+      #   Registers the block as a valid match for the generator.
+      #
+      #   The registered matches are checked when the generator checks whether a
+      #   file path can be generated by the generator. The given block will be
+      #   called with the file path and generator options; if the block returns
+      #   a truthy value, the match check returns true.
+      #
+      #   @yieldparam file_path [String] the input file path provided by the
+      #     user.
+      #   @yieldparam options [Hash] additional options for the generator.
+      #
+      #   @return [void]
+      def match_file(pattern = nil, &block)
+        if abstract?
+          raise AbstractGeneratorError,
+            abstract_generator_message('define matcher')
+        end
+
+        own_matchers << (block_given? ? block : pattern)
+
+        nil
+      end
+
+      # @overload matches?(file_path, **options)
+      #   Checks if the generator matches the given file path and options.
+      #
+      #   @param file_path [String] the input file path provided by the user.
+      #   @param options [Hash] additional options for the generator.
+      #
+      #   @return [true, false] true if the generator can generate files with
+      #   the given file type, path, and options; otherwise false.
+      def matches?(file_path, **)
+        matchers.any? do |matcher|
+          case matcher
+          when Proc   then matcher.call(file_path, **)
+          when Regexp then matcher.match?(file_path)
+          when String then file_path.end_with?(matcher)
+          else
+            # :nocov:
+            false
+            # :nocov:
+          end
+        end
+      end
+      alias match? matches?
+
+      # Registers an output file for the generator.
+      #
+      # The output path parameter is a String that can include format strings,
+      # which will be resolved from the options passed to the generator. In
+      # addition, the format strings can reference the following parameters
+      # derived from the input file_path. The following examples use an input
+      # file path of "lib/path/to/file.rb":
+      #
+      # - base_name: The last segment of the file path, including the file
+      #   extension. Example: "file.rb".
+      # - dir_name: The directory path from the file path, relative to the
+      #   working directory. Example: "lib/path/to".
+      # - ext_name: The extension of the file path, including the leading
+      #   period character. Example: ".rb".
+      # - file_path: The full file path. Example: "lib/path/to/file.rb".
+      # - relative_path: The *second and later* segments of the directory path,
+      #   or an empty String if the path is too short. Example: "path/to".
+      # - root_path: The *first* segment of the directory path, or an empty
+      #   String if the path is too short. Example: "lib".
+      # - short_name: The last segment of the file path, excluding the file
+      #   extension. Example: "file".
+      #
+      # @param path [String] the file path for the generated file.
+      # @param key [String, Symbol] a unique key used to identify the output.
+      #   Defaults to :default.
+      # @param template [String] the path to the template file for the output.
+      #   If not provided, the user must provide a template for that output.
+      #
+      # @return [void]
+      def output(path, key: :default, template: nil) # rubocop:disable Metrics/MethodLength
+        key = key.to_sym
+
+        if abstract?
+          raise AbstractGeneratorError,
+            abstract_generator_message("define output #{key.inspect}")
+        end
+
+        if own_outputs.key?(key)
+          raise OutputAlreadyExistsError, output_already_exists_message(key)
+        end
+
+        template = resolve_template(template)
+
+        own_outputs[key] = Output.new(key:, path:, template:)
+
+        nil
+      end
+
+      # @return [Hash{Symbol => Output}] the configured outputs for the
+      #   generator.
+      def outputs
+        return {} if abstract?
+
+        superclass.outputs.merge(own_outputs)
+      end
+
+      protected
+
+      def matchers
+        return [] if abstract?
+
+        superclass.matchers.concat(own_matchers)
+      end
+
+      def own_matchers = @own_matchers ||= []
+
+      def own_outputs = @own_outputs ||= {}
+
+      private
+
+      def abstract_generator_message(short_message)
+        class_name =
+          ancestors
+          .find { |ancestor| ancestor.is_a?(Class) && ancestor.name }
+          .name
+
+        "unable to #{short_message} - #{class_name} is an abstract class"
+      end
+
+      def output_already_exists_message(key)
+        class_name =
+          ancestors
+          .find { |ancestor| ancestor.is_a?(Class) && ancestor.name }
+          .name
+
+        "unable to define output #{key.inspect} - #{class_name} already " \
+          "defines output #{key.inspect}"
+      end
+
+      def resolve_template(maybe_template)
+        return if maybe_template.nil?
+
+        Cuprum::Cli::Files::Templates.resolve(maybe_template)
+      end
+    end
+
+    abstract
+
+    provider Cuprum::Cli::Dependencies.provider
+
+    dependency :file_system
+    dependency :standard_io
+
+    option :directories, type: :boolean, default: true
+    option :dry_run,     type: :boolean
+
+    # @overload initialize(file_path, **options)
+    #   @param file_path [String, nil] the input file path provided by the user.
+    #   @param options [Hash] additional options for the generator.
+    #
+    #   @option options dry_run [true, false] if true, simulates file generation
+    #     but does not perform the actual file system operations. Defaults to
+    #     false.
+    #   @option options quiet [true, false] if true, does not print generated
+    #     file names status to STDOUT. Defaults to false.
+    #   @option options verbose [true, false] if true, prints the contents of
+    #     generated files to STDOUT. Defaults to false.
+    def initialize(file_path = nil, **)
+      super()
+
+      @file_path = file_path
+      @options   = self.class.resolve_options(**)
+    end
+
+    # @return [String] the input file path provided by the user.
+    attr_reader :file_path
+
+    # @return [Hash] additional options for the generator.
+    attr_reader :options
+
+    # @return [Hash] parameters extracted from the input file name.
+    def file_parameters
+      @file_parameters ||=
+        if file_path
+          extract_file_parameters(file_path)
+        else
+          {}
+        end
+    end
+
+    # @return [Hash] parameters used to resolve output file paths and contents.
+    def parameters
+      file_parameters.merge(options)
+    end
+
+    private
+
+    def build_file_template(template_path)
+      Cuprum::Cli::Files::Templates::FileTemplate.build(template_path)
+    end
+
+    def check_if_file_already_exists(file_path:)
+      return unless file_system.file?(file_path)
+
+      error  =
+        file_not_writeable_error(file_path:, reason: 'file already exists')
+
+      failure(error)
+    end
+
+    def check_if_file_is_directory(file_path:)
+      return unless file_system.directory?(file_path)
+
+      error  =
+        file_not_writeable_error(file_path:, reason: 'file is a directory')
+
+      failure(error)
+    end
+
+    def create_file(contents:, file_path:)
+      Cuprum::Cli::Files::CreateFile
+        .new(
+          directories: directories?,
+          dry_run:     dry_run?,
+          file_system:
+        )
+        .call(contents:, file_path:)
+    end
+
+    def duplicate_file_error(file_path:, key:)
+      details = "multiple outputs writing to output path #{file_path.inspect}"
+
+      generator_error(details:, key:)
+    end
+
+    def extract_file_parameters(file_path) # rubocop:disable Metrics/MethodLength
+      base_name = File.basename(file_path)
+      segments  = file_path.split(File::SEPARATOR)
+
+      {
+        base_name:,
+        dir_name:      File.dirname(file_path),
+        ext_name:      File.extname(file_path),
+        file_path:,
+        relative_path: segments[1...-1].join(File::SEPARATOR),
+        root_path:     segments[0...-1].first || '',
+        short_name:    base_name.split('.').first
+      }
+    end
+
+    def file_not_writeable_error(**)
+      Cuprum::Cli::Files::Errors::FileNotWriteable.new(**)
+    end
+
+    def filter_outputs # rubocop:disable Metrics/MethodLength
+      outputs = self.class.outputs
+
+      if outputs.empty?
+        error = generator_error(
+          details: 'generator does not define any outputs'
+        )
+        return failure(error)
+      end
+
+      outputs = outputs.reject { |key, _| options[key] == false }
+
+      return outputs unless outputs.empty?
+
+      error = generator_error(details: 'all outputs have been disabled')
+      failure(error)
+    end
+
+    def generate_file(contents:, file_path:)
+      say "Generating file #{file_path}..."
+
+      report_file_contents(contents)
+
+      step { create_file(contents:, file_path:) }
+
+      file_path
+    end
+
+    def generate_contents(outputs) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      outputs.each_value.with_object({}) do |output, hsh|
+        file_path = step { resolve_output_path(output) }
+
+        if hsh.key?(file_path)
+          return failure(duplicate_file_error(file_path:, key: output.key))
+        end
+
+        template  = step { template_for(output) }
+        contents  = step { render_template(template:) }
+
+        step { check_if_file_is_directory(file_path:) }
+        step { check_if_file_already_exists(file_path:) }
+
+        hsh[file_path] = contents
+      end
+    end
+
+    def generator_error(details: nil, key: nil)
+      message = 'unable to generate output file'
+      message = "#{message}#{key ? " #{key.inspect}" : 's'}"
+      message = "#{message} - #{details}" if details
+
+      Cuprum::Cli::Files::Errors::GeneratorError.new(
+        details:,
+        file_path:,
+        message:,
+        options:
+      )
+    end
+
+    def process
+      outputs = step { filter_outputs }
+
+      generated_files = step { generate_contents(outputs) }
+
+      generated_files.each do |file_path, contents|
+        step { generate_file(contents:, file_path:) }
+      end
+
+      generated_files.keys
+    end
+
+    def render_template(template:)
+      if template.members.include?(:file_system)
+        template = template.with(file_system:)
+      end
+
+      template.call(**parameters)
+    end
+
+    def report_file_contents(contents)
+      say "\n", verbose: true
+      say(
+        contents
+          .each_line
+          .map { |line| line == "\n" ? "\n" : "  #{line}" }.join,
+        verbose: true
+      )
+      say "\n", verbose: true
+    end
+
+    def resolve_output_path(output) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      format(output.path, parameters.compact).gsub(%r{//+}, '/')
+    rescue ArgumentError => exception
+      raise unless exception.message.include?('malformed format string')
+
+      details = "#{exception.message} for output path #{output.path}"
+      error   = generator_error(details:, key: output.key)
+      failure(error)
+    rescue KeyError => exception
+      details =
+        "missing parameter #{exception.key.inspect} for output path " \
+        "#{output.path}"
+      error   = generator_error(details:, key: output.key)
+      failure(error)
+    end
+
+    def template_for(output)
+      template_path = template_path_from_options(output)
+
+      unless template_path.nil? || template_path.empty?
+        return build_file_template(template_path)
+      end
+
+      return output.template if output.template
+
+      error = generator_error(
+        details: 'output does not define a template path',
+        key:     output.key
+      )
+      failure(error)
+    end
+
+    def template_path_from_options(output)
+      if output.key == :default && options.key?(:template)
+        return options[:template]
+      end
+
+      options[:"#{output.key}_template"]
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/files/generators'
+
+module Cuprum::Cli::Files::Generators
+  # Generator for creating a file with specified file path and contents.
+  class BasicGenerator < Cuprum::Cli::Files::Generator
+    option :contents,  type: :string, required: true
+
+    option :file_path, type: :string, required: true
+
+    output '%<file_path>s',
+      template: Cuprum::Cli::Files::Templates::BasicTemplate.new
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/files/generators'
+
+module Cuprum::Cli::Files::Generators
+  # Generator for creating an RSpec source file.
+  class RSpecGenerator < Cuprum::Cli::Files::Generator
+    match_file(/_spec\.rb\z/)
+
+    option :rspec_template
+
+    output '%<file_path>s',
+      key:      :rspec,
+      template: File.join(
+        Cuprum::Cli::Files::Generators::TEMPLATES_PATH,
+        'rspec.rb.erb'
+      )
+  end
+end