operandi 5.0.0

data/lib/operandi/config.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Operandi
+  class << self
+    # Configure Operandi with a block.
+    #
+    # @yield [Config] the configuration object
+    # @return [void]
+    #
+    # @example
+    #   Operandi.configure do |config|
+    #     config.require_arg_type = true
+    #     config.require_output_type = true
+    #     config.use_transactions = false
+    #   end
+    def configure
+      yield config
+    end
+
+    # Get the global configuration object.
+    #
+    # @return [Config] the configuration instance
+    def config
+      @config ||= Config.new
+    end
+  end
+
+  # Configuration class for Operandi global settings.
+  #
+  # @example Accessing configuration
+  #   Operandi.config.require_arg_type # => true
+  #
+  # @example Modifying configuration
+  #   Operandi.config.use_transactions = false
+  class Config
+    # @return [Boolean] whether arguments must have a type specified
+    attr_reader :require_arg_type
+
+    # @return [Boolean] whether outputs must have a type specified
+    attr_reader :require_output_type
+
+    # @return [Boolean] whether to wrap service execution in a database transaction
+    attr_reader :use_transactions
+
+    # @return [Boolean] whether to copy errors to parent service in chain
+    attr_reader :load_errors
+
+    # @return [Boolean] whether to stop executing steps when an error is added
+    attr_reader :break_on_error
+
+    # @return [Boolean] whether to raise Operandi::RuntimeError when service fails
+    attr_reader :raise_on_error
+
+    # @return [Boolean] whether to rollback the transaction when an error is added
+    attr_reader :rollback_on_error
+
+    # @return [Boolean] whether to copy warnings to parent service in chain
+    attr_reader :load_warnings
+
+    # @return [Boolean] whether to stop executing steps when a warning is added
+    attr_reader :break_on_warning
+
+    # @return [Boolean] whether to raise Operandi::RuntimeError when service has warnings
+    attr_reader :raise_on_warning
+
+    # @return [Boolean] whether to rollback the transaction when a warning is added
+    attr_reader :rollback_on_warning
+
+    # @return [Hash{String => String}] custom type mappings for Ruby LSP addon.
+    #   Maps custom types to Ruby types for hover/completion.
+    #   @example { "CustomTypes::UUID" => "String", "CustomTypes::Money" => "BigDecimal" }
+    attr_reader :ruby_lsp_type_mappings
+
+    DEFAULTS = {
+      require_arg_type: true,
+      require_output_type: true,
+      use_transactions: true,
+
+      load_errors: true,
+      break_on_error: true,
+      raise_on_error: false,
+      rollback_on_error: true,
+
+      load_warnings: true,
+      break_on_warning: false,
+      raise_on_warning: false,
+      rollback_on_warning: false,
+
+      ruby_lsp_type_mappings: {}.freeze,
+    }.freeze
+
+    DEFAULTS.each_key do |name|
+      define_method(:"#{name}=") do |value|
+        instance_variable_set(:"@#{name}", value)
+        @to_h = nil # Invalidate memoized hash
+      end
+    end
+
+    # Convenience setter for backward compatibility.
+    # Sets both require_arg_type and require_output_type.
+    #
+    # @param value [Boolean] whether to require types for arguments and outputs
+    # @return [void]
+    def require_type=(value)
+      self.require_arg_type = value
+      self.require_output_type = value
+    end
+
+    # Initialize configuration with default values.
+    def initialize
+      reset_to_defaults!
+    end
+
+    # Reset all configuration options to their default values.
+    #
+    # @return [void]
+    def reset_to_defaults!
+      DEFAULTS.each do |key, value|
+        instance_variable_set(:"@#{key}", value)
+      end
+
+      @to_h = nil # Invalidate memoized hash
+    end
+
+    # Convert configuration to a hash.
+    #
+    # @return [Hash{Symbol => Object}] all configuration options as a hash
+    def to_h
+      @to_h ||= DEFAULTS.keys.to_h do |key|
+        [key, public_send(key)]
+      end
+    end
+
+    # Merge configuration with additional options.
+    #
+    # @param config [Hash] options to merge
+    # @return [Hash] merged configuration hash
+    def merge(config)
+      to_h.merge(config)
+    end
+  end
+end

data/lib/operandi/constants.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Operandi
+  # Collection type constants
+  module CollectionTypes
+    ARGUMENTS = :arguments
+    OUTPUTS = :outputs
+
+    ALL = [ARGUMENTS, OUTPUTS].freeze
+  end
+
+  # Field type constants
+  module FieldTypes
+    ARGUMENT = :argument
+    OUTPUT = :output
+
+    ALL = [ARGUMENT, OUTPUT].freeze
+  end
+
+  # Reserved names that cannot be used for arguments, outputs, or steps
+  # These names would conflict with existing gem methods
+  module ReservedNames
+    # Instance methods from Base class and concerns
+    BASE_METHODS = [
+      :arg,
+      :output,
+      :errors,
+      :warnings,
+      :success?,
+      :failed?,
+      :errors?,
+      :warnings?,
+      :stop!,
+      :stopped?,
+      :stop_immediately!,
+      :call,
+      :run_callbacks,
+    ].freeze
+
+    # Class methods that could conflict
+    CLASS_METHODS = [
+      :config,
+      :run,
+      :run!,
+      :with,
+      :arg,
+      :remove_arg,
+      :output,
+      :remove_output,
+      :step,
+      :remove_step,
+      :steps,
+      :outputs,
+      :arguments,
+    ].freeze
+
+    # Callback method names
+    CALLBACK_METHODS = [
+      :before_step_run,
+      :after_step_run,
+      :around_step_run,
+      :on_step_success,
+      :on_step_failure,
+      :on_step_crash,
+      :before_service_run,
+      :after_service_run,
+      :around_service_run,
+      :on_service_success,
+      :on_service_failure,
+    ].freeze
+
+    # Ruby reserved words and common Object methods
+    RUBY_RESERVED = [
+      :initialize,
+      :class,
+      :object_id,
+      :send,
+      :__send__,
+      :public_send,
+      :respond_to?,
+      :method,
+      :methods,
+      :instance_variable_get,
+      :instance_variable_set,
+      :instance_variables,
+      :extend,
+      :include,
+      :new,
+      :allocate,
+      :superclass,
+    ].freeze
+
+    # All reserved names combined (used for validation)
+    ALL = (BASE_METHODS + CALLBACK_METHODS + RUBY_RESERVED).uniq.freeze
+  end
+end

data/lib/operandi/dsl/arguments_dsl.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+require_relative "validation"
+
+module Operandi
+  module Dsl
+    # DSL for defining and managing service arguments
+    module ArgumentsDsl
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Define an argument for the service
+        #
+        # @param name [Symbol] the argument name
+        # @param opts [Hash] options for configuring the argument
+        # @option opts [Class, Array<Class>] :type Type(s) to validate against
+        #   (e.g., String, Integer, [String, Symbol])
+        # @option opts [Boolean] :optional (false) Whether nil values are allowed
+        # @option opts [Object, Proc] :default Default value or proc to evaluate in instance context
+        # @option opts [Boolean] :context (false) Whether to pass this argument to child services
+        #
+        # @example Define a required string argument
+        #   arg :name, type: String
+        #
+        # @example Define an optional argument with default
+        #   arg :age, type: Integer, optional: true, default: 25
+        #
+        # @example Define an argument with multiple allowed types
+        #   arg :id, type: [String, Integer]
+        #
+        # @example Define an argument with proc default
+        #   arg :timestamp, type: Time, default: -> { Time.now }
+        #
+        # @example Define a context argument passed to child services
+        #   arg :current_user, type: User, context: true
+        def arg(name, opts = {})
+          Validation.validate_symbol_name!(name, :argument, self)
+          Validation.validate_reserved_name!(name, :argument, self)
+          Validation.validate_name_conflicts!(name, :argument, self)
+          Validation.validate_type_required!(name, :argument, self, opts)
+
+          own_arguments[name] = Settings::Field.new(name, self, opts.merge(field_type: FieldTypes::ARGUMENT))
+          @arguments = nil # Clear memoized arguments since we're modifying them
+        end
+
+        # Remove an argument from the service
+        #
+        # @param name [Symbol] the argument name to remove
+        def remove_arg(name)
+          own_arguments.delete(name)
+          @arguments = nil # Clear memoized arguments since we're modifying them
+        end
+
+        # Get all arguments including inherited ones
+        #
+        # @return [Hash] all arguments defined for this service
+        def arguments
+          @arguments ||= build_arguments
+        end
+
+        # Get only arguments defined in this class
+        #
+        # @return [Hash] arguments defined in this class only
+        def own_arguments
+          @own_arguments ||= {}
+        end
+
+        private
+
+        # Build arguments by merging inherited arguments with own arguments
+        #
+        # @return [Hash] merged arguments
+        def build_arguments
+          inherited = superclass.respond_to?(:arguments) ? superclass.arguments.dup : {}
+          inherited.merge(own_arguments)
+        end
+      end
+    end
+  end
+end

data/lib/operandi/dsl/outputs_dsl.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+require_relative "validation"
+
+module Operandi
+  module Dsl
+    # DSL for defining and managing service outputs
+    module OutputsDsl
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Define an output for the service
+        #
+        # @param name [Symbol] the output name
+        # @param opts [Hash] options for configuring the output
+        # @option opts [Class, Array<Class>] :type Type(s) to validate against
+        #   (e.g., Hash, String, [String, Symbol])
+        # @option opts [Boolean] :optional (false) Whether nil values are allowed
+        # @option opts [Object, Proc] :default Default value or proc to evaluate in instance context
+        #
+        # @example Define a required hash output
+        #   output :result, type: Hash
+        #
+        # @example Define an optional output with default
+        #   output :status, type: String, optional: true, default: "pending"
+        #
+        # @example Define an output with multiple allowed types
+        #   output :data, type: [Hash, Array]
+        #
+        # @example Define an output with proc default
+        #   output :metadata, type: Hash, default: -> { {} }
+        def output(name, opts = {})
+          Validation.validate_symbol_name!(name, :output, self)
+          Validation.validate_reserved_name!(name, :output, self)
+          Validation.validate_name_conflicts!(name, :output, self)
+          Validation.validate_type_required!(name, :output, self, opts)
+
+          own_outputs[name] = Settings::Field.new(name, self, opts.merge(field_type: FieldTypes::OUTPUT))
+          @outputs = nil # Clear memoized outputs since we're modifying them
+        end
+
+        # Remove an output from the service
+        #
+        # @param name [Symbol] the output name to remove
+        def remove_output(name)
+          own_outputs.delete(name)
+          @outputs = nil # Clear memoized outputs since we're modifying them
+        end
+
+        # Get all outputs including inherited ones
+        #
+        # @return [Hash] all outputs defined for this service
+        def outputs
+          @outputs ||= build_outputs
+        end
+
+        # Get only outputs defined in this class
+        #
+        # @return [Hash] outputs defined in this class only
+        def own_outputs
+          @own_outputs ||= {}
+        end
+
+        private
+
+        # Build outputs by merging inherited outputs with own outputs
+        #
+        # @return [Hash] merged outputs
+        def build_outputs
+          inherited = superclass.respond_to?(:outputs) ? superclass.outputs.dup : {}
+          inherited.merge(own_outputs)
+        end
+      end
+    end
+  end
+end

data/lib/operandi/dsl/steps_dsl.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+require_relative "validation"
+
+module Operandi
+  module Dsl
+    # DSL for defining and managing service steps
+    module StepsDsl
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Define a step for the service
+        #
+        # @param name [Symbol] the step name (must correspond to a private method)
+        # @param opts [Hash] options for configuring the step
+        # @option opts [Symbol, Proc] :if Condition to determine if step should run
+        # @option opts [Symbol, Proc] :unless Condition to skip step (returns truthy to skip)
+        # @option opts [Boolean] :always (false) Run step even after errors/warnings
+        # @option opts [Symbol] :before Insert this step before the specified step
+        # @option opts [Symbol] :after Insert this step after the specified step
+        #
+        # @example Define a simple step
+        #   step :validate_input
+        #
+        # @example Define a conditional step
+        #   step :send_notification, if: :should_notify?
+        #   step :skip_validation, unless: :production?
+        #
+        # @example Define a step that always runs
+        #   step :cleanup, always: true
+        #
+        # @example Define step ordering
+        #   step :log_start, before: :validate_input
+        #   step :log_end, after: :process_data
+        #
+        # @example Define a step with proc condition
+        #   step :premium_feature, if: -> { user.premium? && feature_enabled? }
+        def step(name, opts = {}) # rubocop:disable Metrics/MethodLength
+          Validation.validate_symbol_name!(name, :step, self)
+          Validation.validate_reserved_name!(name, :step, self)
+          Validation.validate_name_conflicts!(name, :step, self)
+          validate_step_opts!(name, opts)
+
+          # Build current steps to check for duplicates and find insertion targets
+          current = steps
+          if current.key?(name)
+            raise Operandi::Error,
+                  "Step `#{name}` is already defined in service #{self}. Each step must have a unique name."
+          end
+
+          if (target = opts[:before] || opts[:after]) && !current.key?(target)
+            available = current.keys.join(", ")
+            raise Operandi::Error,
+                  "Cannot find target step `#{target}` in service #{self}. Available steps: [#{available}]"
+          end
+
+          step_obj = Settings::Step.new(name, self, opts)
+
+          if opts[:before] || opts[:after]
+            step_operations << { action: :insert,
+                                 name: name,
+                                 step: step_obj,
+                                 before: opts[:before],
+                                 after: opts[:after], }
+          else
+            step_operations << { action: :add, name: name, step: step_obj }
+          end
+
+          # Clear memoized steps since we're modifying them
+          @steps = nil
+        end
+
+        # Remove a step from the service
+        #
+        # @param name [Symbol] the step name to remove
+        def remove_step(name)
+          step_operations << { action: :remove, name: name }
+
+          # Clear memoized steps since we're modifying them
+          @steps = nil
+        end
+
+        # Get all steps including inherited ones
+        #
+        # @return [Hash] all steps defined for this service
+        def steps
+          @steps ||= build_steps
+        end
+
+        # Get the list of step operations to be applied
+        #
+        # @return [Array] list of operations
+        def step_operations
+          @step_operations ||= []
+        end
+
+        # Validate that the service has steps defined
+        # Called before executing the service
+        #
+        # @raise [NoStepsError] if no steps are defined
+        def validate_steps!
+          return unless steps.empty?
+
+          raise Operandi::NoStepsError,
+                "Service #{self} has no steps defined. Define at least one step or implement a `run` method."
+        end
+
+        private
+
+        # Validate step options to ensure they are valid
+        #
+        # @param name [Symbol] the step name
+        # @param opts [Hash] the step options
+        def validate_step_opts!(name, opts)
+          return unless opts[:before] && opts[:after]
+
+          raise Operandi::Error, "You cannot specify `before` and `after` " \
+                                 "for step `#{name}` in service #{self} at the same time"
+        end
+
+        # Build steps by applying operations to inherited steps
+        #
+        # @return [Hash] the final steps hash
+        def build_steps
+          # Start with inherited steps
+          result = inherit_steps
+
+          # Apply operations in order
+          step_operations.each { |op| apply_step_operation(result, op) }
+
+          # If no steps defined, check for `run` method as fallback
+          result[:run] = Settings::Step.new(:run, self, {}) if result.empty? && instance_method_defined?(:run)
+
+          result
+        end
+
+        # Check if an instance method is defined in this class or its ancestors
+        # (excluding Operandi::Base and its modules)
+        #
+        # @param method_name [Symbol] the method name to check
+        # @return [Boolean] true if the method is defined
+        def instance_method_defined?(method_name)
+          # Check if method exists and is not from base service classes
+          return false unless method_defined?(method_name) || private_method_defined?(method_name)
+
+          # Get the method owner to ensure it's defined in user's service class
+          owner = instance_method(method_name).owner
+
+          # Method should be defined in a class that inherits from Base,
+          # not in Base itself or its included modules
+          !owner.to_s.start_with?("Operandi")
+        end
+
+        # Inherit steps from parent class
+        #
+        # @return [Hash] inherited steps
+        def inherit_steps
+          superclass.respond_to?(:steps) ? superclass.steps.dup : {}
+        end
+
+        # Apply a single step operation to the steps hash
+        #
+        # @param steps [Hash] the steps hash
+        # @param operation [Hash] the operation to apply
+        def apply_step_operation(steps, operation)
+          case operation[:action]
+          when :add
+            steps[operation[:name]] = operation[:step]
+          when :remove
+            steps.delete(operation[:name])
+          when :insert
+            insert_step(steps, operation)
+          end
+        end
+
+        # Insert a step before or after a target step
+        #
+        # @param steps [Hash] the steps hash
+        # @param operation [Hash] the insert operation details
+        def insert_step(steps, operation)
+          target = operation[:before] || operation[:after]
+          keys = steps.keys
+          index = keys.index(target)
+          return unless index
+
+          # More efficient insertion using ordered hash reconstruction
+          new_steps = {}
+
+          keys.each_with_index do |key, i|
+            # Insert before target
+            new_steps[operation[:name]] = operation[:step] if operation[:before] && i == index
+            new_steps[key] = steps[key]
+
+            # Insert after target
+            new_steps[operation[:name]] = operation[:step] if operation[:after] && i == index
+          end
+
+          steps.replace(new_steps)
+        end
+      end
+    end
+  end
+end