highway 0.0.1 → 1.0.1

data/lib/highway/steps/parameters/base.rb

@@ -0,0 +1,52 @@
+#
+# base.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+module Highway
+  module Steps
+    module Parameters
+
+      # This class is a base abstract class for other classes in this
+      # module. You should not use it directly.
+      class Base
+
+        public
+
+        # Initialize an instance.
+        def initialize()
+          raise NotImplementedError.new("You must not call `#{__method__.to_s}` on `#{self.class.to_s}`.")
+        end
+
+        # Name of the parameter.
+        #
+        # @return [String]
+        attr_reader :name
+
+        # Whether the parameter is required.
+        #
+        # @return [Boolean]
+        def is_required?
+          @required
+        end
+
+        # Typecheck and validate a value of the parameter.
+        #
+        # This method returns typechecked, coerced and validated value or raises
+        # a fatal error if value has invalid type, can't be coerced or is
+        # othweriwse invalid.
+        #
+        # @param value [Object] A value.
+        # @param interface [Highway::Interface] An interface instance.
+        # @param keypath [Array<String>] A keypath to be used for debugging purposes.
+        #
+        # @return [Object]
+        def typecheck_and_validate(value, interface:, keypath: [])
+          raise NotImplementedError.new("You must override `#{__method__.to_s}` in `#{self.class.to_s}`.")
+        end
+
+      end
+
+    end
+  end
+end

data/lib/highway/steps/parameters/compound.rb

@@ -0,0 +1,141 @@
+#
+# compound.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+require "highway/steps/parameters/base"
+
+module Highway
+  module Steps
+    module Parameters
+
+      # This class is used in step definition classes to represent a compound
+      # parameter of a step that consists of other parameters.
+      class Compound < Parameters::Base
+
+        # Initialize an instance.
+        #
+        # @param name [String] Name of the parameter.
+        # @param required [Boolean] Whether parametr is required.
+        # @param defaults [Boolean] Whether to construct default value from child parameters.
+        # @param children [Array<Highway::Steps::Parameters::*>] Child parameters.
+        def initialize(name:, required:, defaults: false, children:)
+          @name = name
+          @required = required
+          @defaults = defaults
+          @children = children
+        end
+
+        # Child parameters.
+        #
+        # @return [Array<Highway::Steps::Parameters::*>]
+        attr_reader :children
+
+        # Find a child parameter definition by name.
+        #
+        # @param name [String] Name of the parameter
+        #
+        # @return [Highway::Steps::Parameters::*]
+        def find_child_for_name(name)
+          @children.find { |child| child.name == name }
+        end
+
+        # Default value of the parameter.
+        #
+        # @return [Hash, nil]
+        def default
+          if @defaults
+            Utilities::hash_map(@children) { |child| [child.name, child.default] }
+          end
+        end
+
+        # Typecheck and validate a value of the parameter.
+        #
+        # This method returns typechecked, coerced and validated value or raises
+        # a fatal error if value has invalid type, can't be coerced or is
+        # othweriwse invalid.
+        #
+        # @param value [Object] A value.
+        # @param interface [Highway::Interface] An interface instance.
+        # @param keypath [Array<String>] A keypath to be used for debugging purposes.
+        #
+        # @return [Object]
+        def typecheck_and_validate(values, interface:, keypath: [])
+
+          unless values.is_a?(Hash)
+            interface.fatal!("Invalid type of value for parameter: '#{Utilities::keypath_to_s(keypath)}'.")
+          end
+
+          @children.each { |child|
+            if child.is_required? && !values.keys.include?(child.name) && child.default == nil
+              interface.fatal!("Missing value for required parameter: '#{Utilities::keypath_to_s(keypath + [child.name])}'.")
+            end
+          }
+
+          values.keys.each { |name|
+            unless find_child_for_name(name)
+              expected = @children.map { |child| "'#{child.name}'" }.join(", ")
+              interface.fatal!("Unknown parameter: '#{Utilities::keypath_to_s(keypath + [name])}'. Expected one of: [#{expected}].")
+            end
+          }
+
+          typechecked = Utilities::hash_map(values) { |name, value|
+            child = find_child_for_name(name)
+            [name, child.typecheck_and_validate(value, interface: interface, keypath: keypath + [name])]
+          }
+
+          (default || {}).merge(typechecked)
+
+        end
+
+        # Typecheck and prevalidate a value of the parameter. This method is
+        # used during the initial prevalidation of step parameter values before
+        # evaluating all the values.
+        #
+        # This method works in a similar way to `typecheck_and_validate` with
+        # one difference: if it encounters a single parameter whose value
+        # is (or contains) `:ignore` symbol, it doesn't perform any typechecking
+        # and validation on it. That way, the caller can specify which values
+        # should be fully validated and which should be ignored.
+        #
+        # @param value [Object] A value.
+        # @param interface [Highway::Interface] An interface instance.
+        # @param keypath [Array<String>] A keypath to be used for debugging purposes.
+        #
+        # @return [Void]
+        def typecheck_and_prevalidate(values, interface:, keypath: [])
+
+          unless values.is_a?(Hash)
+            interface.fatal!("Invalid type of value for parameter: '#{Utilities::keypath_to_s(keypath)}'.")
+          end
+
+          @children.each { |child|
+            if child.is_required? && !values.keys.include?(child.name) && child.default == nil
+              interface.fatal!("Missing value for required parameter: '#{Utilities::keypath_to_s(keypath + [child.name])}'.")
+            end
+          }
+
+          values.keys.each { |name|
+            unless find_child_for_name(name)
+              expected = @children.map { |child| "'#{child.name}'" }.join(", ")
+              interface.fatal!("Unknown parameter: '#{Utilities::keypath_to_s(keypath + [name])}'. Expected one of: [#{expected}].")
+            end
+          }
+
+          values.each_pair { |name, value|
+            if (child = find_child_for_name(name))
+              if child.is_a?(Parameters::Compound)
+                child.typecheck_and_prevalidate(value, interface: interface, keypath: keypath + [name])
+              elsif !Utilities::recursive_include?(value, :ignore)
+                child.typecheck_and_validate(value, interface: interface, keypath: keypath + [name])
+              end
+            end
+          }
+
+        end
+
+      end
+
+    end
+  end
+end

data/lib/highway/steps/parameters/single.rb

@@ -0,0 +1,74 @@
+#
+# single.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+require "highway/steps/parameters/base"
+
+module Highway
+  module Steps
+    module Parameters
+
+      # This class is used in step definition classes to represent a single
+      # parameter of a step.
+      class Single < Parameters::Base
+
+        public
+
+        # Initialize an instance.
+        #
+        # @param name [String] Name of the parameter.
+        # @param type [Highway::Steps::Types::*] Type of the parameter.
+        # @param required [Boolean] Whether parametr is required.
+        # @param default [Object, nil] Default value of the parameter.
+        def initialize(name:, type:, required:, default: nil)
+          @name = name
+          @required = required
+          @type = type
+          @default = default
+          assert_default_value_valid()
+        end
+
+        # Type of the parameter.
+        #
+        # @return [Highway::Steps::Types::*]
+        attr_reader :type
+
+        # Default value of the parameter.
+        #
+        # @return [Object, nil]
+        attr_reader :default
+
+        # Typecheck and validate a value of the parameter.
+        #
+        # This method returns typechecked, coerced and validated value or raises
+        # a fatal error if value has invalid type, can't be coerced or is
+        # othweriwse invalid.
+        #
+        # @param value [Object] A value.
+        # @param interface [Highway::Interface] An interface instance.
+        # @param keypath [Array<String>] A keypath to be used for debugging purposes.
+        #
+        # @return [Object]
+        def typecheck_and_validate(value, interface:, keypath: [])
+          typechecked = @type.typecheck_and_validate(value)
+          if typechecked != nil
+            typechecked
+          else
+            interface.fatal!("Invalid value: '#{value}' for parameter: '#{Utilities::keypath_to_s(keypath)}'.")
+          end
+        end
+
+        private
+
+        def assert_default_value_valid()
+          if @default != nil && @type.typecheck_and_validate(@default) == nil
+            raise ArgumentError.new("Default value: '#{@default}' is not a valid value for parameter: '#{@name}'.")
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/highway/steps/registry.rb

@@ -0,0 +1,92 @@
+#
+# registry.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+require "highway/steps/step"
+
+module Highway
+  module Steps
+
+    # This class is responsible for keeping track of available steps.
+    class Registry
+
+      public
+
+      # Initialize an instance.
+      def initialize()
+        @classes = Set.new()
+      end
+
+      # Initialize an instance and automatically load all steps in the default
+      # library.
+      #
+      # @return [Highway::Steps::Registry]
+      def self.new_and_load_default_library()
+
+        registry = self.new()
+
+        Dir[File.expand_path('library/*.rb', File.dirname(__FILE__))].each do |file|
+          require(file)
+        end
+
+        unless Highway::Steps.const_defined?("Library")
+          return
+        end
+
+        Highway::Steps::Library.constants.each do |step_symbol|
+          step_class = Highway::Steps::Library.const_get(step_symbol)
+          if step_class_valid?(step_class)
+            registry.register(step_class)
+          end
+        end
+
+        registry
+
+      end
+
+      # Add a new step definition class to the registry. Is it is already
+      # registered, this does nothing.
+      #
+      # @param step_class [Class] The step definition class.
+      #
+      # @raise [ArgumentError] If trying to register an invalid step class.
+      #
+      # @return [Void]
+      def register(step_class)
+        if self.class.step_class_valid?(step_class)
+          @classes.add(step_class)
+        else
+          raise ArgumentError.new("Step class `#{step_class}` is invalid.")
+        end
+      end
+
+      # Remove a step definition class from the registry. If it is not
+      # registered, this does nothing.
+      #
+      # @param step_class [Class] The step definition class.
+      #
+      # @return [Void]
+      def unregister(step_class)
+        @classes.remove(step_class)
+      end
+
+      # Get a step definition class by its name.
+      #
+      # @param step_name [String] The step name.
+      #
+      # @return [Class, nil]
+      def get_by_name(step_name)
+        @classes.find { |step_class| step_class.name == step_name }
+      end
+
+      private
+
+      def self.step_class_valid?(step_class)
+        step_class.is_a?(Class) && step_class < Highway::Steps::Step
+      end
+
+    end
+
+  end
+end

data/lib/highway/steps/step.rb

@@ -0,0 +1,52 @@
+#
+# step.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+require "highway/steps/parameters/compound"
+
+module Highway
+  module Steps
+
+    # This class serves as a base class for all step definition classes. It
+    # contains a common API and some useful utilities.
+    class Step
+
+      public
+
+      # Name of the step as it appears in configuration file.
+      #
+      # @return [String]
+      def self.name
+        raise NotImplementedError.new("You must override `#{__method__.to_s}` in `#{self.class.to_s}`.")
+      end
+
+      # Parameters that this step recognizes.
+      #
+      # @return [Array<Highway::Steps::Parameters::*>]
+      def self.parameters
+        raise NotImplementedError.new("You must override `#{__method__.to_s}` in `#{self.class.to_s}`.")
+      end
+
+      # The root parameter that nests all parameters of the step.
+      #
+      # @return [Highway::Steps::Parameters::Compound]
+      def self.root_parameter
+        return Parameters::Compound.new(name: "root", required: true, defaults: true, children: parameters)
+      end
+
+      # Run the step in given context containing inputs and Fastlane runner.
+      #
+      # @param parameters [Hash] Parameters of the step.
+      # @param context [Highway::Runtime::Context] The runtime context.
+      # @param report [Highway::Runtime::Report] The current runtime report.
+      #
+      # @return [Void]
+      def self.run(parameters:, context:, report:)
+        raise NotImplementedError.new("You must override `#{__method__.to_s}` in `#{self.class.to_s}`.")
+      end
+
+    end
+
+  end
+end

data/lib/highway/steps/types/any.rb

@@ -0,0 +1,65 @@
+#
+# any.rb
+# Copyright © 2019 Netguru S.A. All rights reserved.
+#
+
+module Highway
+  module Steps
+    module Types
+
+      # This class represents any parameter type. It can be used in parameters
+      # which should not perform any type checking.
+      class Any
+
+        public
+
+        # Initialize an instance.
+        #
+        # @param validate [Proc] A custom value validation block.
+        def initialize(validate: nil)
+          @validate = validate
+        end
+
+        # Typecheck and coerce a value if possible.
+        #
+        # This method returns a typechecked and coerced value or `nil` if value
+        # has invalid type and can't be coerced.
+        #
+        # @param value [Object] A value.
+        #
+        # @return [Object, nil]
+        def typecheck(value)
+          value
+        end
+
+        # Validate the typechecked value against a custom validation block.
+        #
+        # This method returns `true` if value is valid or `false` if value is
+        # invalid.
+        #
+        # @param value [Object] A value.
+        #
+        # @return [Boolean]
+        def validate(value)
+          return true if @validate == nil
+          @validate.call(value)
+        end
+
+        # Typecheck and validate the value at the same time.
+        #
+        # This method returns typechecked, coerced and validated value or `nil`
+        # if value has invalid type, can't be coerced or is invalid.
+        #
+        # @param value [Object] A value.
+        #
+        # @return [Object, nil]
+        def typecheck_and_validate(value)
+          typechecked = typecheck(value)
+          typechecked if !typechecked.nil? && validate(typechecked)
+        end
+
+      end
+
+    end
+  end
+end