cuprum-cli 0.1.0

data/lib/cuprum/cli/dependencies/file_system/mock.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/dependencies/file_system'
+
+module Cuprum::Cli::Dependencies
+  # Mock implementation of FileSystem for testing purposes.
+  class FileSystem::Mock < Cuprum::Cli::Dependencies::FileSystem # rubocop:disable Metrics/ClassLength
+    SINGLE_GLOB_PATTERN = /\*+/
+    private_constant :SINGLE_GLOB_PATTERN
+
+    # Exception raised when trying to read from or write to a non-mocked path.
+    class InvalidPathError < StandardError; end
+
+    # Utility class used to simulate tempfile behavior.
+    class MockTempfile < SimpleDelegator
+      # @param path [String] the qualified path to the tempfile.
+      def initialize(path)
+        super(StringIO.new)
+
+        @path = path
+      end
+
+      # @return [String] the qualified path to the tempfile.
+      attr_reader :path
+    end
+
+    # @param files [Hash{String => Hash, IO}] the mocked directories and files.
+    #   Must be a Hash with String keys representing file path segments; Hash
+    #   values represent directories, while IO values represent files.
+    # @param root_path [String] the path to the root directory. Defaults to the
+    #   value of `Dir.pwd`.
+    def initialize(files: {}, root_path: Dir.pwd)
+      super(root_path:)
+
+      @files     = files
+      @tempfiles = []
+    end
+
+    # @return [Hash{String => Hash, IO}] the mocked directories and files.
+    attr_reader :files
+
+    # @return [Array<String>] the contents of each generated tempfile.
+    attr_reader :tempfiles
+
+    # (see Cuprum::Cli::Dependencies::FileSystem#create_directory)
+    def create_directory(path, recursive: false) # rubocop:disable Metrics/MethodLength
+      tools.assertions.validate_name(path, as: 'path')
+
+      *dir_names, dir_name = split_path(resolve_path(path))
+
+      directory = write_directory(
+        *dir_names,
+        action:       'create directory',
+        file_or_path: path,
+        recursive:
+      )
+
+      if io_stream?(directory[dir_name])
+        raise DirectoryIsAFileError,
+          "unable to create directory #{path} - directory is a file"
+      end
+
+      directory[dir_name] = {}
+
+      path
+    end
+    alias make_directory create_directory
+
+    # (see Cuprum::Cli::Dependencies::FileSystem#directory?)
+    def directory?(path)
+      tools.assertions.validate_name(path, as: 'path')
+
+      path = resolve_path(path)
+      mock = resolve_mock(path)
+
+      mock.is_a?(Hash)
+    end
+    alias directory_exists? directory?
+
+    # (see Cuprum::Cli::Dependencies::FileSystem#each_file)
+    def each_file(pattern, &)
+      return enum_for(:each_file, pattern) unless block_given?
+
+      flattened_files.each do |file_path|
+        next unless matches_pattern?(file_path:, pattern:)
+
+        yield File.join(root_path, file_path)
+      end
+
+      nil
+    end
+
+    # (see Cuprum::Cli::Dependencies::FileSystem#directory?)
+    def file?(path)
+      tools.assertions.validate_name(path, as: 'path')
+
+      path = resolve_path(path)
+      mock = resolve_mock(path)
+
+      io_stream?(mock)
+    end
+    alias file_exists? file?
+
+    # (see Cuprum::Cli::Dependencies::FileSystem#read_file)
+    def read_file(file_or_path) # rubocop:disable Metrics/MethodLength
+      validate_file(file_or_path, as: 'file')
+
+      return file_or_path.read if io_stream?(file_or_path)
+
+      path = resolve_path(file_or_path)
+
+      unless path.start_with?(root_path)
+        raise FileNotFoundError,
+          "unable to read file #{file_or_path} - file not found"
+      end
+
+      mock = resolve_mock(path)
+
+      return mock.tap(&:rewind).read if io_stream?(mock)
+
+      if mock
+        raise FileIsADirectoryError,
+          "unable to read file #{file_or_path} - file is a directory"
+      end
+
+      raise FileNotFoundError,
+        "unable to read file #{file_or_path} - file not found"
+    end
+    alias read read_file
+
+    # (see Cuprum::Cli::Dependencies::FileSystem#with_tempfile)
+    def with_tempfile(&block)
+      file_name = SecureRandom.uuid
+      file_path = File.join(root_path, 'tempfiles', file_name)
+
+      tempfile = MockTempfile.new(file_path)
+
+      (files['tempfiles'] ||= {})[file_name] = tempfile
+
+      block.call(tempfile).tap do
+        tempfiles << read_file(tempfile.tap(&:rewind))
+      end
+    ensure
+      files['tempfiles'].delete(file_name)
+    end
+
+    # (see Cuprum::Cli::Dependencies::FileSystem#write_file)
+    def write_file(file_or_path, data) # rubocop:disable Metrics/MethodLength
+      validate_file(file_or_path, as: 'file')
+
+      return file_or_path.write(data) if io_stream?(file_or_path)
+
+      path = resolve_path(file_or_path)
+
+      unless path.start_with?(root_path)
+        raise DirectoryNotFoundError,
+          "unable to write file #{file_or_path} - directory not found"
+      end
+
+      mock = resolve_mock(path)
+
+      if mock.is_a?(MockTempfile)
+        mock.write(data)
+        mock.rewind
+
+        return
+      end
+
+      if mock.nil? || io_stream?(mock)
+        return write_mock_file(path, data, file_or_path)
+      end
+
+      raise FileIsADirectoryError,
+        "unable to write file #{file_or_path} - file is a directory"
+    end
+    alias write write_file
+
+    private
+
+    def flatten_files(files:, flat: [], path: '')
+      files.each do |name, value|
+        qualified_path = path.empty? ? name : File.join(path, name)
+
+        next flat << qualified_path unless value.is_a?(Hash)
+
+        flatten_files(files: value, flat:, path: qualified_path)
+      end
+
+      flat
+    end
+
+    def flattened_files
+      @flattened_files || flatten_files(files:)
+    end
+
+    def io_stream?(file_or_path)
+      super || file_or_path.is_a?(MockTempfile)
+    end
+
+    def matches_globbed_pattern?(entry_names:, pattern_strings:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      prefix_index   = pattern_strings.index { |str| str.include?('**') }
+      prefix_strings = pattern_strings[...prefix_index]
+      prefix_count   = prefix_strings.length
+      suffix_index   = pattern_strings.rindex { |str| str.include?('**') }
+      suffix_strings = pattern_strings[(1 + suffix_index)..]
+      suffix_count   = suffix_strings.length
+
+      return false unless entry_names.length >= prefix_count + suffix_count
+
+      entry_names[...prefix_count]
+        .zip(prefix_strings)
+        .concat(entry_names[-suffix_count...].zip(suffix_strings))
+        .all? do |entry_name, pattern_string|
+          matches_pattern_string?(entry_name:, pattern_string:)
+        end
+    end
+
+    def matches_pattern?(file_path:, pattern:)
+      entry_names     = file_path.split(File::SEPARATOR)
+      pattern_strings = pattern.split(File::SEPARATOR)
+
+      if pattern_strings.any? { |str| str.include?('**') }
+        return matches_globbed_pattern?(entry_names:, pattern_strings:)
+      end
+
+      return false unless entry_names.length == pattern_strings.length
+
+      entry_names.zip(pattern_strings).all? do |entry_name, pattern_string|
+        matches_pattern_string?(entry_name:, pattern_string:)
+      end
+    end
+
+    def matches_pattern_string?(entry_name:, pattern_string:)
+      if pattern_string.include?('*')
+        pattern_string
+          .gsub('.', '\.')
+          .gsub(SINGLE_GLOB_PATTERN, '.*')
+          .then { |str| Regexp.new(str) }
+          .match?(entry_name)
+      else
+        entry_name == pattern_string
+      end
+    end
+
+    def resolve_mock(path)
+      return unless path.start_with?(root_path)
+
+      *rest, last = split_path(path)
+
+      dir = rest.reduce(files) do |dir, segment|
+        break if dir[segment].nil? || io_stream?(dir[segment])
+
+        dir[segment]
+      end
+
+      dir&.[](last)
+    end
+
+    def split_path(path)
+      path[(1 + root_path.length)..]
+        &.split(File::SEPARATOR) || []
+    end
+
+    def write_directory(*dir_names, action:, file_or_path:, recursive: false)
+      dir_names.reduce(files) do |dir, dir_name|
+        if io_stream?(dir[dir_name])
+          raise DirectoryIsAFileError,
+            "unable to #{action} #{file_or_path} - directory is a file"
+        elsif dir[dir_name].nil? && !recursive
+          raise DirectoryNotFoundError,
+            "unable to #{action} #{file_or_path} - directory not found"
+        end
+
+        dir[dir_name] ||= {}
+      end
+    end
+
+    def write_mock_file(path, data, file_or_path)
+      *dir_names, file_name = split_path(path)
+
+      directory = write_directory(
+        *dir_names,
+        action:       'write file',
+        file_or_path:,
+        recursive:    false
+      )
+
+      directory[file_name] = StringIO.new(data.to_s)
+    end
+
+    def validate_file(file_or_path, as:)
+      return if file_or_path.is_a?(MockTempfile)
+
+      super
+    end
+  end
+end

data/lib/cuprum/cli/dependencies/file_system.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'stringio'
+require 'tempfile'
+
+require 'cuprum/cli/dependencies'
+
+module Cuprum::Cli::Dependencies
+  # Utility wrapping filesystem operations.
+  class FileSystem # rubocop:disable Metrics/ClassLength
+    autoload :Mock, 'cuprum/cli/dependencies/file_system/mock'
+
+    # Abstract class for exceptions raised by failing file system operations.
+    class FileError < StandardError; end
+
+    # Exception raised when attempting to access a file as a directory.
+    class DirectoryIsAFileError < FileError; end
+
+    # Exception raised when attempting to access a non-existent directory.
+    class DirectoryNotFoundError < FileError; end
+
+    # Exception raised when attempting to access a directory as a file.
+    class FileIsADirectoryError < FileError; end
+
+    # Exception raised when attempting to access a non-existent file.
+    class FileNotFoundError < FileError; end
+
+    # @param root_path [String] the path to the root directory. Defaults to the
+    #   value of `Dir.pwd`.
+    def initialize(root_path: Dir.pwd)
+      @root_path = root_path
+    end
+
+    # @return [String] the path to the root directory.
+    attr_reader :root_path
+
+    # Creates a directory at the requested path.
+    #
+    # @param path [String] the path to the directory.
+    # @param recursive [true, false] if true, creates any required intermediate
+    #   directories, equivalent to the -p flag on `mkdir`. Defaults to false.
+    #
+    # @return [String] the path to the created directory.
+    def create_directory(path, recursive: false)
+      tools.assertions.validate_name(path, as: 'path')
+
+      resolved = resolve_path(path)
+
+      return path if directory?(resolved)
+
+      handle_create_errors(path) do
+        recursive ? FileUtils.mkdir_p(resolved) : FileUtils.mkdir(resolved)
+      end
+
+      path
+    end
+    alias make_directory create_directory
+
+    # Checks if the requested directory exists.
+    #
+    # @param path [String] the path to the requested directory.
+    #
+    # @return [true, false] true if the directory exists and is a directory,
+    #   otherwise false.
+    def directory?(path)
+      tools.assertions.validate_name(path, as: 'path')
+
+      path = resolve_path(path)
+
+      File.exist?(path) && File.directory?(path)
+    end
+    alias directory_exists? directory?
+
+    # @overload each_file
+    #   Iterates over file names matching the given pattern.
+    #
+    #   @param pattern [String] the file pattern to match.
+    #
+    #   @return [Enumerator<String>] an enumerator over the matching file names.
+    #
+    # @overload each_file { |file| }
+    #   Yields each file name matching the given pattern.
+    #
+    #   @param pattern [String] the file pattern to match.
+    #
+    #   @return [nil]
+    #
+    #   @yieldparam [String] the matching file name.
+    def each_file(pattern, &)
+      return enum_for(:each_file, pattern) unless block_given?
+
+      path = resolve_path(pattern)
+
+      Dir[path].each(&)
+
+      nil
+    end
+
+    # Checks if the requested file exists.
+    #
+    # @param path [String] the path to the requested file.
+    #
+    # @return [true, false] true if the file exists and is a file,
+    #   otherwise false.
+    def file?(path)
+      tools.assertions.validate_name(path, as: 'path')
+
+      path = resolve_path(path)
+
+      File.exist?(path) && File.file?(path)
+    end
+    alias file_exists? file?
+
+    # @overload read_file(file)
+    #   Reads the contents of the given file or IO stream.
+    #
+    #   @param file [IO] the file to read.
+    #
+    #   @return [String] the file contents.
+    #
+    # @overload read_file(path)
+    #   Reads the contents of the file at the given path.
+    #
+    #   @param path [String] the file path to read.
+    #
+    #   @return [String] the file contents.
+    #
+    #   @raise [FileIsADirectoryError] if the requested file is a directory.
+    #   @raise [FileNotFoundError] if the requested file is not found.
+    def read_file(file_or_path)
+      validate_file(file_or_path, as: 'file')
+
+      return file_or_path.read if io_stream?(file_or_path)
+
+      path = resolve_path(file_or_path)
+
+      File.read(path)
+    rescue Errno::EISDIR
+      raise FileIsADirectoryError,
+        "unable to read file #{file_or_path} - file is a directory"
+    rescue Errno::ENOENT
+      raise FileNotFoundError,
+        "unable to read file #{file_or_path} - file not found"
+    end
+    alias read read_file
+
+    # Creates a tempfile and passes it to the block.
+    #
+    # @yieldparam [File] the generated tempfile.
+    #
+    # @return [Object] the value returned by the block.
+    def with_tempfile(&) = Tempfile.create(&)
+
+    # @overload write_file(file, data)
+    #   Writes the data to the given file or IO stream.
+    #
+    #   @param file [IO] the file to write.
+    #   @param data [String] the data to write.
+    #
+    #   @return [Integer] the number of bytes written.
+    #
+    # @overload write_file(path, data)
+    #   Writes the data to the file at the given path.
+    #
+    #   @param path [String] the file path to write.
+    #   @param data [String] the data to write.
+    #
+    #   @return [Integer] the number of bytes written.
+    #
+    #   @raise [DirectoryIsAFileError] if the path to the requested file
+    #     includes an existing file.
+    #   @raise [DirectoryNotFoundError] if the directory for the requested file
+    #     is not found.
+    #   @raise [FileIsADirectoryError] if the requested file is a directory.
+    def write_file(file_or_path, data)
+      validate_file(file_or_path, as: 'file')
+
+      return file_or_path.write(data) if io_stream?(file_or_path)
+
+      path = resolve_path(file_or_path)
+
+      handle_write_errors(file_or_path) { File.write(path, data) }
+    end
+    alias write write_file
+
+    private
+
+    def empty_file_message(as:)
+      tools.assertions.error_message_for('presence', as:)
+    end
+
+    def handle_create_errors(path)
+      yield
+    rescue Errno::EEXIST
+      raise Cuprum::Cli::Dependencies::FileSystem::DirectoryIsAFileError,
+        "unable to create directory #{path} - directory is a file"
+    rescue Errno::ENOENT
+      raise Cuprum::Cli::Dependencies::FileSystem::DirectoryNotFoundError,
+        "unable to create directory #{path} - directory not found"
+    end
+
+    def handle_write_errors(file_or_path)
+      yield
+    rescue Errno::EISDIR
+      raise FileIsADirectoryError,
+        "unable to write file #{file_or_path} - file is a directory"
+    rescue Errno::ENOENT
+      raise DirectoryNotFoundError,
+        "unable to write file #{file_or_path} - directory not found"
+    rescue Errno::ENOTDIR
+      raise DirectoryIsAFileError,
+        "unable to write file #{file_or_path} - directory is a file"
+    end
+
+    def invalid_file_message(as:)
+      "#{as} is not a String or IO stream"
+    end
+
+    def io_stream?(file_or_path)
+      file_or_path.is_a?(IO) || file_or_path.is_a?(StringIO)
+    end
+
+    def resolve_path(path)
+      return path if File.absolute_path?(path)
+
+      File.expand_path(File.join(root_path, path))
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def validate_file(file_or_path, as:)
+      case file_or_path
+      in IO | StringIO
+        nil
+      in nil | ''
+        raise ArgumentError, empty_file_message(as:)
+      in String # rubocop:disable Lint/DuplicateBranch
+        nil
+      else
+        raise ArgumentError, invalid_file_message(as:)
+      end
+    end
+  end
+end

data/lib/cuprum/cli/dependencies/standard_io/helpers.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/dependencies/standard_io'
+
+module Cuprum::Cli::Dependencies
+  # Helper methods for reading from and writing to standard inputs and outputs.
+  module StandardIo::Helpers
+    # String input values that will be mapped to a boolean false.
+    FALSY_VALUES = Set.new(%w[f false n no]).freeze
+
+    # Pattern matching a valid integer input.
+    INTEGER_PATTERN = /\A-?\d+([\d_,]+\d)?\z/
+
+    # String input values that will be mapped to a boolean true.
+    TRUTHY_VALUES = Set.new(%w[t true y yes]).freeze
+
+    # @overload ask(prompt = nil, caret: true, format: nil, strip: true, **options)
+    #   Requests an input from the input stream.
+    #
+    #   @param prompt [String, nil] the prompt to display to the user, if any.
+    #   @param options [Hash] options for requesting the input.
+    #
+    #   @option options caret [true, false] if true, prints a caret "> " to the
+    #     output stream after the prompt. Defaults to true when the newline
+    #     option is true, otherwise false.
+    #   @option options format [String, Symbol] the expected format of the
+    #     input. Valid values are :string (the default), :boolean, and :integer.
+    #     The input string will be transformed into the given format, or an
+    #     exception raised if the value cannot be transformed.
+    #   @option options newline [true, false] if true, a newline will be printed
+    #     after the prompt if a prompt is given.
+    #   @option options strip [true, false] if true, strips the trailing newline
+    #     from the input. Defaults to true.
+    #
+    #   @return [String, Integer, true, false, nil] the received and formatted
+    #     input value, or nil if the input value was empty.
+    def ask( # rubocop:disable Metrics/ParameterLists
+      prompt = nil,
+      caret:   nil,
+      format:  nil,
+      newline: true,
+      strip:   true,
+      **
+    )
+      validate_prompt(prompt)
+      display_prompt(caret:, newline:, prompt:)
+
+      value = standard_io.read_input&.then { |str| strip ? str.strip : str }
+
+      return if value.nil? || value.empty?
+      return value if format.nil?
+
+      send(:"format_#{format}", value)
+    end
+
+    # @overload say(message, newline: true, quiet: false, verbose: false, **options)
+    #   Prints a message to the output stream.
+    #
+    #   @param message [String] the message to print.
+    #   @param options [Hash] options for printing the message.
+    #
+    #   @option options newline [true, false] if true, appends a newline to the
+    #     message if the message does not end with a newline. Defaults to true.
+    #   @option options quiet [true, false] if true, prints the message even if
+    #     the command has the :quiet option enabled. Defaults to false. Ignored
+    #     if
+    #     the command does not support the :quiet option.
+    #   @option options verbose [true, false] if true, prints the message only
+    #     if the command has the :verbose option enabled. Defaults to false.
+    #     Ignored if the command does not support the :verbose option.
+    #
+    #   @return [nil]
+    def say(message, newline: true, **)
+      validate_message(message)
+
+      standard_io.write_output(message, newline:)
+    end
+
+    # @overload warn(message, **options)
+    #   Prints a message to the error stream.
+    #
+    #   @param message [String] the message to print.
+    #   @param options [Hash] options for printing the message.
+    #
+    #   @option options newline [true, false] if true, appends a newline to the
+    #     message if the message does not end with a newline. Defaults to true.
+    #
+    #   @return [nil]
+    def warn(message, newline: true, **)
+      validate_message(message)
+
+      standard_io.write_error(message, newline:)
+    end
+
+    private
+
+    def display_prompt(caret:, newline:, prompt:)
+      standard_io.write_output(prompt, newline:) if prompt
+
+      return unless caret.nil? ? newline : caret
+
+      standard_io.write_output('> ', newline: false)
+    end
+
+    def format_boolean(value)
+      Cuprum::Cli::Coercion.coerce_boolean(value.strip)
+    rescue Cuprum::Cli::Coercion::CoercionError
+      nil
+    end
+
+    def format_integer(value)
+      Cuprum::Cli::Coercion.coerce_integer(value.strip)
+    rescue Cuprum::Cli::Coercion::CoercionError
+      nil
+    end
+
+    def tools = SleepingKingStudios::Tools::Toolbelt.instance
+
+    def validate_message(message)
+      tools.assertions.validate_instance_of(
+        message,
+        as:       'message',
+        expected: String
+      )
+    end
+
+    def validate_prompt(prompt)
+      return if prompt.nil?
+
+      tools.assertions.validate_instance_of(
+        prompt,
+        as:       'prompt',
+        expected: String
+      )
+      tools.assertions.validate_presence(prompt, as: 'prompt')
+    end
+  end
+end