hotstepper 0.1.0

data/lib/hotstepper/support/file_wrapper.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Support
+    # A wrapper around a file that we want to generate, which knows how to generate
+    # its own path and name based on the namespace it's in.
+    class FileWrapper
+      include Dry::Core::Equalizer.new(:namespace, :name)
+
+      # @return [String]
+      TAB = "  "
+
+      private_constant :TAB
+
+      # @return [String]
+      attr_reader :extension
+
+      # @return [String]
+      attr_reader :filename
+
+      # The full constant name of the class or module, including its namespace.
+      # @return [String]
+      attr_reader :full_name
+
+      # The proper base constant name of the class or module,
+      # without its namespace.
+      # @return [String]
+      attr_reader :name
+
+      # @return [Hotstepper::Support::NamespaceWrapper]
+      attr_reader :namespace
+
+      # The namespaced_file path to the object, suitable for use with `File.join`,
+      # absent any of the Rails paths. For example, "Foo::Bar::Baz" would become `["foo", "bar", "baz.rb"]`.
+      # @return [<String>]
+      attr_reader :path
+
+      # @param [#to_s] input
+      # @param [Hotstepper::Support::NamespaceWrapper] namespace
+      def initialize(input, namespace:, extension: "rb")
+        @extension = extension
+
+        @namespace = namespace
+
+        # Ensure that our input is a properly camelized constant name.
+        # It uses ActiveSupport's inflector at runtime, so it should
+        # respect whatever custom inflections the user has defined.
+        @name = input.to_s.camelize(:upper).demodulize
+
+        @filename = [name.underscore, extension].compact_blank.join(?.).freeze
+
+        @full_name = [*namespace.parts, name].join("::")
+
+        @path = [*namespace.path, filename].freeze
+      end
+
+      # @return [Pathname]
+      def to_operation_path = operations_root.join(*path)
+
+      # @return [Pathname]
+      def to_service_path = services_root.join(*path)
+
+      private
+
+      # @return [Pathname]
+      def app_root = Pathname("app")
+
+      # @return [Pathname]
+      def operations_root = app_root.join("operations")
+
+      # @return [Pathname]
+      def services_root = app_root.join("services")
+    end
+  end
+end

data/lib/hotstepper/support/generators/common.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Support
+    module Generators
+      module Common
+        extend ActiveSupport::Concern
+
+        private
+
+        # @return [Hotstepper::Support::NamespaceWrapper]
+        attr_reader :namespace
+
+        # @return [Pathname]
+        def operations_root = Rails.root.join("app", "operations")
+
+        # @return [Pathname]
+        def services_root = Rails.root.join("app", "services")
+
+        # @param [#to_s] input
+        # @return [void]
+        def set_up_wrapped_namespace!(input)
+          @namespace = Hotstepper::Support::NamespaceWrapper.new(input)
+        end
+
+        # @param [#to_s] input
+        # @return [Hotstepper::Support::FileWrapper]
+        def namespaced_file(input) = namespace.file(input)
+
+        # @return [void]
+        def nest_under_namespace(&)
+          content = capture(&)
+
+          concat(namespace.wrap(content))
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/support/generators/namespaced.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Support
+    module Generators
+      module Namespaced
+        extend ActiveSupport::Concern
+
+        include Common
+
+        included do
+          argument :namespace_name, type: :string, required: true,
+            desc: "The namespace that the services and operations should live in"
+        end
+
+        # @return [void]
+        def set_up_namespace!
+          set_up_wrapped_namespace!(namespace_name)
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/support/generators/service_operations.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Support
+    module Generators
+      module ServiceOperations
+        extend ActiveSupport::Concern
+
+        include Common
+        include Namespaced
+      end
+    end
+  end
+end

data/lib/hotstepper/support/generators/step_definition.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Support
+    module Generators
+      class StepDefinition < Hotstepper::Struct
+        include ActiveModel::Validations
+
+        PARSE_PATTERN = /\A(?<name>.+?)(?<is_abstract>\?|:abstract)?\z/
+
+        attribute :name, Hotstepper::Support::Types::Coercible::Symbol
+        attribute :abstract, Hotstepper::Support::Types::Bool.default(false)
+        attribute :index, Hotstepper::Support::Types::Integer.default(0)
+
+        validates :name, presence: true, format: { with: Hotstepper::Patterns::STEP_NAME }
+
+        alias abstract? abstract
+
+        def name! = "#{name}!"
+
+        class << self
+          # @param [String] input
+          # @return [StepDefinition]
+          def parse(input, index: 0)
+            match = PARSE_PATTERN.match(input)
+
+            unless match
+              raise ArgumentError, "Invalid step definition: #{input.inspect}"
+            end
+
+            new(
+              index:,
+              name: match[:name],
+              abstract: match[:is_abstract].present?
+            )
+          end
+
+          # @param [<String>] inputs
+          # @return [<StepDefinition>]
+          def parse_many(inputs) = inputs.map.with_index { |input, index| parse(input, index:) }
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/support/namespace_wrapper.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Support
+    class NamespaceWrapper
+      include Dry::Core::Equalizer.new(:namespace)
+
+      TAB = "  "
+
+      # @return [String]
+      attr_reader :namespace
+
+      # @return [<String>]
+      attr_reader :parts
+
+      # @return [<String>]
+      attr_reader :path
+
+      # @return [Integer]
+      attr_reader :size
+
+      # @param [#to_s] input
+      def initialize(input)
+        # Ensure that our input is a properly camelized constant name.
+        # It uses ActiveSupport's inflector at runtime, so it should
+        # respect whatever custom inflections the user has defined.
+        @namespace = input.to_s.camelize(:upper)
+
+        @parts = namespace.split("::")
+
+        @path = parts.map(&:underscore)
+
+        @size = parts.size
+      end
+
+      def empty? = size.zero?
+
+      # @param [#to_s] input
+      # @return [Hotstepper::Support::FileWrapper]
+      def file(input)
+        Hotstepper::Support::FileWrapper.new(input, namespace: self)
+      end
+
+      # @param [String] content
+      # @return [String]
+      def wrap(content)
+        # :nocov:
+        return content if empty?
+        # :nocov:
+
+        sio = StringIO.new
+
+        parts.each_with_index do |part, index|
+          indentation = TAB * index
+
+          sio.puts "#{indentation}module #{part}"
+        end
+
+        sio.puts content.strip.indent(size * 2)
+
+        last_index = size - 1
+
+        last_index.downto(0).each do |index|
+          indentation = TAB * index
+
+          sio.puts "#{indentation}end"
+        end
+
+        sio.string
+      end
+    end
+  end
+end

data/lib/hotstepper/support/null_service.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Support
+    # @api private
+    # @see Hotstepper::Operation
+    class NullService
+      include Dry::Monads[:result]
+
+      # @return [Dry::Monads::Result]
+      def call(*args, **kwargs) = Success()
+    end
+  end
+end

data/lib/hotstepper/support/types.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "../patterns"
+
+module Hotstepper
+  module Support
+    # DRY.rb types used within this gem.
+    #
+    # @api private
+    module Types
+      extend Hotstepper::Typespace
+
+      DatabaseConnectionClass = ClassOrSubclass(ActiveRecord::Base)
+
+      ServiceClass = Class
+
+      SimpleSortDirection = Coercible::String.default("asc").enum("asc", "desc").fallback("asc")
+
+      StepName = Coercible::Symbol.constrained(format: Hotstepper::Patterns::STEP_NAME)
+
+      UUID = String.constrained(any_uuid: true)
+
+      UUIDList = Types::Array.of(Types::UUID)
+    end
+  end
+end

data/lib/hotstepper/testing/do_for.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Testing
+    class DoFor
+      extend Hotstepper::Monadic::DoFor
+
+      include Dry::Monads[:result]
+
+      def do_method
+        value = yield try_something!
+
+        Success value
+      end
+
+      do_for! :do_method
+
+      private
+
+      def try_something! = Success("tried")
+    end
+  end
+end

data/lib/hotstepper/testing/operations.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Testing
+    module Operations
+      module ExampleHelpers
+        extend RSpec::Matchers::DSL
+
+        # @return [Dry::Monads::Result, Object]
+        attr_reader :last_result
+
+        # @return [Object]
+        attr_reader :last_success
+
+        # @return [Object]
+        attr_reader :last_failure
+
+        def expect_calling
+          @last_result = operation.call
+
+          expect(@last_result)
+        ensure
+          extract_last_result!
+        end
+
+        def expect_calling_with(...)
+          @last_result = operation.call(...)
+
+          expect(@last_result)
+        ensure
+          extract_last_result!
+        end
+
+        # @api private
+        # @return [void]
+        def extract_last_result!
+          case @last_result
+          in Dry::Monads::Success
+            @last_success = @last_result.value!
+            @last_failure = nil
+          in Dry::Monads::Failure
+            @last_success = nil
+            @last_failure = @last_result.failure
+          else
+            @last_success = @last_failure = nil
+          end
+        end
+
+        matcher :be_the_result_with do |*args, **kwargs|
+          match do |actual|
+            @expected = operation.call(*args, **kwargs)
+
+            if @expected.success?
+              values_match? @expected.value!, actual
+            else
+              false
+            end
+          end
+
+          description do
+            "be the result of calling #{operation.class.name}(#{inspect_args})"
+          end
+
+          define_method :inspect_args do
+            [
+              *inspect_value(args),
+              inspect_value(kwargs)
+            ].join(", ")
+          end
+
+          def inspect_value(value)
+            case value
+            when Array then value.map { |v| inspect_value v }
+            when Hash then value.transform_values { |v| inspect_value v }
+            when Hotstepper::Support::Types::Any.constrained(model: true)
+              "Model(#{value.model_name}##{value.to_param.inspect})"
+            when Hotstepper::Support::Types::Any.constrained(model_class: true)
+              "ModelClass(#{value.model_name})"
+            when String, Symbol then value.inspect
+            else
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/testing/typing.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Testing
+    module Typing
+      module Interface
+        extend Hotstepper::Typing
+      end
+
+      class Foo
+        include Hotstepper::Typing
+        include Interface
+      end
+
+      class Bar < Foo; end
+    end
+  end
+end

data/lib/hotstepper/testing.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  # Testing utilities for hotstepper.
+  module Testing
+  end
+end
+
+begin
+  require "rspec/core"
+  require "rspec/matchers"
+rescue LoadError
+  # :nocov:
+  warn "RSpec is required for hotstepper testing utilities. Please add it to your Gemfile."
+
+  return
+  # :nocov:
+else
+  require_relative "../testing/matchers/00_disable_with"
+  require_relative "../testing/matchers/dry_validation"
+  require_relative "../testing/matchers/monadic"
+  require_relative "../testing/matchers/negated"
+  require_relative "../testing/contexts/operations"
+end

data/lib/hotstepper/typespace.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  # Enhance a module to act as a `Dry.Types` namespace with some extra
+  # helper methods that build on what `dry-types` provides out of the box.
+  #
+  # @note Unlike `Dry.Types`, this should be `extended` rather than `included`.
+  module Typespace
+    include Dry.Types
+
+    # @return [Module] A memoized version of the `Dry.Types` module, which
+    #   is stored to avoid needing to compile a new set of types with every
+    #   new typespace.
+    CORE_TYPES = Dry.Types
+
+    private_constant :CORE_TYPES
+
+    # @api private
+    module CommonTypes
+      # @return [Dry::Types::Type(String)]
+      Email = CORE_TYPES::String.constrained(email: true)
+
+      # An interface type that matches anything that responds to `#call`.
+      # @return [Dry::Types::Type(#call)]
+      Operation = CORE_TYPES::Any.constrained(respond_to: :call)
+    end
+
+    include CommonTypes
+
+    # @return [Dry::Types::Type(Pathname)]
+    Pathname = Instance(Pathname).constructor do |input|
+      case input
+      when ::String then Pathname(input)
+      when ::Pathname then input
+      else
+        input
+      end
+    end
+
+    class << self
+      # @return [void]
+      def included(_mod)
+        raise TypeError, "use #extend to apply Hotstepper::Types to a module"
+      end
+
+      # @return [void]
+      # @!parse [ruby]
+      #   # An interface type that matches anything that responds to `#call`.
+      #   Operation = Dry::Types["any"].constrained(respond_to: :call)
+      def extended(mod)
+        mod.include CORE_TYPES
+        mod.include CommonTypes
+        mod.include ::Hotstepper::Patterns
+      end
+    end
+
+    # Create a type that matches an exact class or one of its subclasses.
+    #
+    # @param [Class] kls
+    # @return [Dry::Types::Sum::Constrained]
+    def ClassOrSubclass(kls)
+      unless kls.is_a?(::Module)
+        raise ::ArgumentError, "Expected a class or module, got #{kls.inspect}"
+      end
+
+      is_klass = Class.constrained(eql: kls)
+
+      is_klass | Implements(kls)
+    end
+
+    # Create a type that matches a class that includes a given module
+    # @param [Class, Module] mod
+    # @return [Dry::Types::Type]
+    def Implements(mod) = Class.constrained(lt: mod)
+
+    alias Inherits Implements
+
+    # A type that can match a class, one of its subclasses, or an instance
+    # of any of the former.
+    #
+    # @param [Class, Module] type
+    # @return [Dry::Types::Sum::Constrained]
+    def InstanceOrClass(type)
+      unless type.is_a?(::Module)
+        raise ::ArgumentError, "Expected a class or module, got #{type.inspect}"
+      end
+
+      instance = Instance(type)
+
+      klass = ClassOrSubclass(type)
+
+      instance | klass
+    end
+
+    # This type builder is helpful for avoiding circular dependencies as opposed
+    # to using `Instance` directly, since it doesn't require the class to be defined at the time it's called.
+    #
+    # @param [String] instance_named
+    # @return [Dry::Types::Constrained]
+    def InstanceOf(instance_named) = Any.constrained(instance_named:)
+
+    # @param [String] model_named
+    # @return [Dry::Types::Constrained]
+    def ModelInstance(model_named) = Instance(ActiveRecord::Base).constrained(model_named:)
+
+    extend self
+  end
+end

data/lib/hotstepper/typing.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  # Automatically generate `::Type`, `::List`, and `::Subclass` constants for any class (or module) that includes this.
+  module Typing
+    extend ActiveSupport::Concern
+
+    included do
+      hotstepper_typings!
+    end
+
+    module ClassMethods
+      # @param [Class] subclass
+      # @return [void]
+      def inherited(subclass)
+        super
+
+        subclass.hotstepper_typings!
+      end
+
+      # Generate a configurable "map" type with a certain type of key.
+      #
+      # @param [Dry::Types::Type] key
+      # @param [Symbol] on
+      def map_type!(key: Hotstepper::Support::Types::Coercible::String, on: :Map)
+        const_set on, Hotstepper::Support::Types::Hash.map(key, const_get(:Type))
+      end
+
+      protected
+
+      # @return [void]
+      def hotstepper_typings!
+        type = Hotstepper::Support::Types.Instance(self)
+
+        const_set :Type, type
+
+        list = Hotstepper::Support::Types::Array.of(type)
+
+        const_set :List, list
+
+        subclass = Hotstepper::Support::Types.Implements(self)
+
+        const_set :Subclass, subclass
+      end
+    end
+
+    class << self
+      # Allow our typing module to be applied to modules as well,
+      # so we can more succinctly type interfaces.
+      #
+      # @param [Class, Module] base
+      # @return [void]
+      def extend_object(mod)
+        # :nocov:
+        raise TypeError, "use #include for classes" if mod.kind_of?(Class)
+
+        # Already extended
+        return false if mod.singleton_class < self
+
+        # :nocov:
+
+        super
+
+        mod.extend const_get(:ClassMethods)
+        mod.class_eval(&@_included_block)
+      end
+    end
+  end
+end

data/lib/hotstepper/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  VERSION = "0.1.0"
+end