operandi 5.0.0

data/lib/operandi/dsl/validation.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+
+module Operandi
+  module Dsl
+    # Shared validation logic for DSL modules
+    module Validation
+      # Validate that the name is a symbol
+      #
+      # @param name [Object] the name to validate
+      # @param field_type [Symbol] the type of field (:argument, :output, :step)
+      # @param service_class [Class] the service class for error messages
+      def self.validate_symbol_name!(name, field_type, service_class)
+        return if name.is_a?(Symbol)
+
+        raise Operandi::InvalidNameError,
+              "#{field_type.to_s.capitalize} name must be a Symbol, " \
+              "got #{name.class} (#{name.inspect}) in #{service_class}"
+      end
+
+      # Validate that the name is not a reserved word
+      #
+      # @param name [Symbol] the name to validate
+      # @param field_type [Symbol] the type of field (:argument, :output, :step)
+      # @param service_class [Class] the service class for error messages
+      def self.validate_reserved_name!(name, field_type, service_class)
+        return unless ReservedNames::ALL.include?(name.to_sym)
+
+        raise Operandi::ReservedNameError,
+              "Cannot use `#{name}` as #{field_type} name in #{service_class} - " \
+              "it is a reserved word that conflicts with gem methods"
+      end
+
+      # Validate that the name doesn't conflict with other defined names
+      #
+      # @param name [Symbol] the name to validate
+      # @param field_type [Symbol] the type of field being defined (:argument, :output, :step)
+      # @param service_class [Class] the service class to check for conflicts
+      def self.validate_name_conflicts!(name, field_type, service_class)
+        name_sym = name.to_sym
+
+        case field_type
+        when :argument
+          validate_argument_conflicts!(name_sym, service_class)
+        when :output
+          validate_output_conflicts!(name_sym, service_class)
+        when :step
+          validate_step_conflicts!(name_sym, service_class)
+        end
+      end
+
+      # Validate argument name doesn't conflict with outputs or steps
+      def self.validate_argument_conflicts!(name_sym, service_class)
+        # Check against existing outputs
+        if has_output?(name_sym, service_class)
+          raise Operandi::ReservedNameError,
+                "Cannot use `#{name_sym}` as argument name in #{service_class} - " \
+                "it is already defined as an output"
+        end
+
+        # Check against existing steps
+        if has_step?(name_sym, service_class)
+          raise Operandi::ReservedNameError,
+                "Cannot use `#{name_sym}` as argument name in #{service_class} - " \
+                "it is already defined as a step"
+        end
+      end
+
+      # Validate output name doesn't conflict with arguments or steps
+      def self.validate_output_conflicts!(name_sym, service_class)
+        # Check against existing arguments
+        if has_argument?(name_sym, service_class)
+          raise Operandi::ReservedNameError,
+                "Cannot use `#{name_sym}` as output name in #{service_class} - " \
+                "it is already defined as an argument"
+        end
+
+        # Check against existing steps
+        if has_step?(name_sym, service_class)
+          raise Operandi::ReservedNameError,
+                "Cannot use `#{name_sym}` as output name in #{service_class} - " \
+                "it is already defined as a step"
+        end
+      end
+
+      # Validate step name doesn't conflict with arguments or outputs
+      def self.validate_step_conflicts!(name_sym, service_class)
+        # Check against existing arguments
+        if has_argument?(name_sym, service_class)
+          raise Operandi::ReservedNameError,
+                "Cannot use `#{name_sym}` as step name in #{service_class} - " \
+                "it is already defined as an argument"
+        end
+
+        # Check against existing outputs
+        if has_output?(name_sym, service_class)
+          raise Operandi::ReservedNameError,
+                "Cannot use `#{name_sym}` as step name in #{service_class} - " \
+                "it is already defined as an output"
+        end
+      end
+
+      # Check if a name is already defined as an argument
+      def self.has_argument?(name_sym, service_class)
+        # Check own_arguments (current class)
+        (service_class.respond_to?(:own_arguments) && service_class.own_arguments.key?(name_sym)) ||
+          # Check inherited arguments
+          (service_class.superclass.respond_to?(:arguments) && service_class.superclass.arguments.key?(name_sym))
+      end
+
+      # Check if a name is already defined as an output
+      def self.has_output?(name_sym, service_class)
+        # Check own_outputs (current class)
+        (service_class.respond_to?(:own_outputs) && service_class.own_outputs.key?(name_sym)) ||
+          # Check inherited outputs
+          (service_class.superclass.respond_to?(:outputs) && service_class.superclass.outputs.key?(name_sym))
+      end
+
+      # Check if a name is already defined as a step
+      def self.has_step?(name_sym, service_class)
+        # Check step_operations (current class) for non-removed steps
+        (service_class.respond_to?(:step_operations) &&
+         service_class.step_operations.any? { |op| op[:name] == name_sym && op[:action] != :remove }) ||
+          # Check inherited steps
+          (service_class.superclass.respond_to?(:steps) && service_class.superclass.steps.key?(name_sym))
+      end
+
+      # Validate that the type option is provided when require_type is enabled
+      #
+      # @param name [Symbol] the field name
+      # @param field_type [Symbol] the type of field (:argument, :output)
+      # @param service_class [Class] the service class for error messages
+      # @param opts [Hash] the options hash to check for type
+      def self.validate_type_required!(name, field_type, service_class, opts)
+        return if opts.key?(:type)
+        return unless require_type_enabled_for?(field_type, service_class)
+
+        config_name = field_type == :argument ? "require_arg_type" : "require_output_type"
+        raise Operandi::MissingTypeError,
+              "#{field_type.to_s.capitalize} `#{name}` in #{service_class} must have a type specified " \
+              "(#{config_name} is enabled)"
+      end
+
+      # Check if require_type is enabled for the given field type and service class
+      #
+      # @param field_type [Symbol] the type of field (:argument, :output)
+      # @param service_class [Class] the service class to check
+      # @return [Boolean] whether type is required for the field type
+      def self.require_type_enabled_for?(field_type, service_class)
+        config_key = field_type == :argument ? :require_arg_type : :require_output_type
+
+        # Check class-level config in the inheritance chain, then fall back to global config
+        klass = service_class
+        while klass.respond_to?(:class_config)
+          class_config = klass.class_config
+
+          # Check specific config first (require_arg_type or require_output_type)
+          return class_config[config_key] if class_config&.key?(config_key)
+
+          # Check convenience config (require_type) for backward compatibility
+          return class_config[:require_type] if class_config&.key?(:require_type)
+
+          klass = klass.superclass
+        end
+
+        Operandi.config.public_send(config_key)
+      end
+    end
+  end
+end

data/lib/operandi/exceptions.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Operandi
+  # Base exception class for all Operandi errors.
+  class Error < StandardError; end
+
+  # Raised for failures that occur while a service instance is running.
+  class RuntimeError < Error
+    # @return [Base] the service instance that raised the error
+    attr_reader :service
+
+    # @param message [String, nil] the error message
+    # @param service [Base] the service instance that raised the error
+    def initialize(message = nil, service:)
+      raise ArgumentError, "service is required" unless service
+
+      unless defined?(Operandi::Base) && service.is_a?(Operandi::Base)
+        raise ArgumentError, "service must be an Operandi::Base instance"
+      end
+
+      @service = service
+      super(message)
+    end
+  end
+
+  # Raised when an argument or output value doesn't match the expected type.
+  class ArgTypeError < Error
+    # @return [Class<Base>] the service class associated with the type error
+    attr_reader :service_class
+
+    # @param message [String, nil] the error message
+    # @param service_class [Class<Base>] the service class associated with the type error
+    def initialize(message = nil, service_class:)
+      raise ArgumentError, "service_class is required" unless service_class
+
+      unless defined?(Operandi::Base) &&
+             service_class.is_a?(Class) &&
+             service_class <= Operandi::Base
+        raise ArgumentError, "service_class must be an Operandi::Base subclass"
+      end
+
+      @service_class = service_class
+      super(message)
+    end
+  end
+
+  # Raised when using a reserved name for an argument, output, or step.
+  class ReservedNameError < Error; end
+
+  # Raised when a name is invalid (e.g., not a Symbol).
+  class InvalidNameError < Error; end
+
+  # Raised when a service has no steps defined and no run method.
+  class NoStepsError < Error; end
+
+  # Raised when type is required but not specified for an argument or output.
+  class MissingTypeError < Error; end
+
+  # Control flow exception for stop_immediately!
+  # Not an error - used to halt execution gracefully.
+  class StopExecution < StandardError; end
+
+  # Control flow exception for fail_immediately!
+  # Unlike StopExecution, this exception causes transaction rollback.
+  class FailExecution < StandardError; end
+end

data/lib/operandi/message.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Operandi
+  # Represents a single error or warning message.
+  #
+  # @example Creating a message
+  #   message = Message.new(:name, "can't be blank", break: true)
+  #   message.key    # => :name
+  #   message.text   # => "can't be blank"
+  #   message.break? # => true
+  class Message
+    # @return [Symbol] the key/field this message belongs to
+    attr_reader :key
+
+    # @return [String] the message text
+    attr_reader :text
+
+    # Create a new message.
+    #
+    # @param key [Symbol] the key/field this message belongs to
+    # @param text [String] the message text
+    # @param opts [Hash] additional options
+    # @option opts [Boolean] :break whether to stop step execution
+    # @option opts [Boolean] :rollback whether to rollback the transaction
+    def initialize(key, text, opts = {})
+      @key = key
+      @text = text
+      @opts = opts
+    end
+
+    # Check if this message should stop step execution.
+    #
+    # @return [Boolean] true if break option was set
+    def break?
+      @opts[:break]
+    end
+
+    # Check if this message should trigger a transaction rollback.
+    #
+    # @return [Boolean] true if rollback option was set
+    def rollback?
+      @opts[:rollback]
+    end
+
+    # Return the message text.
+    #
+    # @return [String] the message text
+    def to_s
+      text
+    end
+  end
+end

data/lib/operandi/messages.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Operandi
+  # Collection of error or warning messages, organized by key.
+  #
+  # @example Adding and accessing errors
+  #   errors.add(:name, "can't be blank")
+  #   errors.add(:email, "is invalid")
+  #   errors[:name]  # => [#<Message key: :name, text: "can't be blank">]
+  #   errors.to_h    # => { name: ["can't be blank"], email: ["is invalid"] }
+  class Messages
+    extend Forwardable
+
+    # @!method [](key)
+    #   Get messages for a specific key.
+    #   @param key [Symbol] the key to look up
+    #   @return [Array<Message>, nil] array of messages or nil
+
+    # @!method any?
+    #   Check if there are any messages.
+    #   @return [Boolean] true if messages exist
+
+    # @!method empty?
+    #   Check if the collection is empty.
+    #   @return [Boolean] true if no messages
+
+    # @!method size
+    #   Get number of keys with messages.
+    #   @return [Integer] number of keys
+
+    # @!method keys
+    #   Get all keys with messages.
+    #   @return [Array<Symbol>] array of keys
+
+    # @!method key?(key)
+    #   Check if a key has messages.
+    #   @param key [Symbol] the key to check
+    #   @return [Boolean] true if key has messages
+    def_delegators :@messages,
+                   :[],
+                   :any?,
+                   :empty?,
+                   :size,
+                   :keys,
+                   :values,
+                   :each,
+                   :each_with_index,
+                   :each_with_object,
+                   :key?
+    alias has_key? key?
+
+    # Initialize a new messages collection.
+    #
+    # @param config [Hash] configuration options
+    # @param service [Base] service instance that owns this collection
+    # @option config [Boolean] :break_on_add stop execution when message added
+    # @option config [Boolean] :raise_on_add raise exception when message added
+    # @option config [Boolean] :rollback_on_add rollback transaction when message added
+    def initialize(config = {}, service:)
+      @break = false
+      @config = config
+      @messages = {}
+      @service = service
+    end
+
+    # Get total count of all messages across all keys.
+    #
+    # @return [Integer] total number of messages
+    def count
+      @messages.values.sum(&:size)
+    end
+
+    # Add a message to the collection.
+    #
+    # @param key [Symbol] the key/field for this message
+    # @param texts [String, Array<String>, Message] the message text(s) to add
+    # @param opts [Hash] additional options
+    # @option opts [Boolean] :break override break behavior for this message
+    # @option opts [Boolean] :rollback override rollback behavior for this message
+    # @return [void]
+    # @raise [RuntimeError, Error] if text is nil or empty
+    #
+    # @example Add a single error
+    #   errors.add(:name, "can't be blank")
+    #
+    # @example Add multiple errors
+    #   errors.add(:email, ["is invalid", "is already taken"])
+    def add(key, texts, opts = {})
+      raise_error("Error must be a non-empty string") unless texts
+
+      message = nil
+
+      [*texts].each do |text|
+        message = text.is_a?(Message) ? text : Message.new(key, text, opts)
+
+        raise_error("Error must be a non-empty string") unless valid_error_text?(message.text)
+
+        @messages[key] ||= []
+        @messages[key] << message
+      end
+
+      raise!(message)
+      break!(opts.key?(:break) ? opts[:break] : message.break?)
+      rollback!(opts.key?(:rollback) ? opts[:rollback] : message.rollback?) if !opts.key?(:last) || opts[:last]
+    end
+
+    # Check if step execution should stop.
+    #
+    # @return [Boolean] true if a message triggered a break
+    def break?
+      @break
+    end
+
+    # Copy messages from another source.
+    #
+    # @param entity [ActiveRecord::Base, Base, Hash, #each] source to copy from
+    # @param opts [Hash] options to pass to each added message
+    # @return [void]
+    # @raise [RuntimeError, Error] if entity type is not supported
+    #
+    # @example Copy from ActiveRecord model
+    #   errors.copy_from(user) # copies user.errors
+    #
+    # @example Copy from another service
+    #   errors.copy_from(child_service)
+    def copy_from(entity, opts = {})
+      if defined?(ActiveRecord::Base) && entity.is_a?(ActiveRecord::Base)
+        copy_from(entity.errors.messages, opts)
+      elsif entity.is_a?(Operandi::Base)
+        copy_from(entity.errors, opts)
+      elsif entity.respond_to?(:each)
+        last_index = entity.size - 1
+
+        entity.each_with_index do |(key, message), index|
+          add(key, message, opts.merge(last: index == last_index))
+        end
+      else
+        raise_error("Don't know how to import errors from #{entity}")
+      end
+    end
+    alias from_record copy_from
+
+    # Convert messages to a hash with string values.
+    #
+    # @return [Hash{Symbol => Array<String>}] messages as hash
+    def to_h
+      @messages.to_h.transform_values { |value| value.map(&:to_s) }
+    end
+
+    private
+
+    def valid_error_text?(text)
+      return false unless text.is_a?(String)
+
+      !text.strip.empty?
+    end
+
+    def break!(break_execution)
+      return unless break_execution.nil? ? @config[:break_on_add] : break_execution
+
+      @break = true
+    end
+
+    def raise!(message)
+      return unless @config[:raise_on_add]
+
+      if message.key == :base
+        raise_error(message.text.capitalize.strip)
+      else
+        raise_error("#{message.key.to_s.capitalize} #{message.text}".strip)
+      end
+    end
+
+    def raise_error(message)
+      raise Operandi::RuntimeError.new(message, service: @service)
+    end
+
+    def rollback!(rollback)
+      return unless defined?(ActiveRecord::Rollback)
+      return unless rollback.nil? ? @config[:rollback_on_add] : rollback
+
+      raise ActiveRecord::Rollback
+    end
+  end
+end

data/lib/operandi/rspec/matchers/define_argument.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Operandi
+  module RSpec
+    module Matchers
+      # Matcher for testing argument definitions on a service class
+      #
+      # @example Basic usage
+      #   expect(MyService).to define_argument(:name)
+      #
+      # @example With type constraint
+      #   expect(MyService).to define_argument(:name).with_type(String)
+      #
+      # @example With optional flag
+      #   expect(MyService).to define_argument(:email).optional
+      #
+      # @example With default value
+      #   expect(MyService).to define_argument(:status).with_default("pending")
+      #
+      # @example With context flag
+      #   expect(MyService).to define_argument(:current_user).with_context
+      #
+      # @example Combined
+      #   expect(MyService).to define_argument(:count).with_type(Integer).optional.with_default(0)
+      def define_argument(name)
+        DefineArgumentMatcher.new(name)
+      end
+
+      class DefineArgumentMatcher
+        def initialize(name)
+          @name = name
+          @expected_type = nil
+          @expected_optional = nil
+          @expected_default = nil
+          @check_default = false
+          @expected_context = nil
+        end
+
+        def with_type(type)
+          @expected_type = type
+          self
+        end
+
+        def optional(value = true)
+          @expected_optional = value
+          self
+        end
+
+        def required
+          @expected_optional = false
+          self
+        end
+
+        def with_default(default)
+          @check_default = true
+          @expected_default = default
+          self
+        end
+
+        def with_context(value = true)
+          @expected_context = value
+          self
+        end
+
+        def matches?(service_class)
+          @service_class = service_class
+          @actual_class = service_class.is_a?(Class) ? service_class : service_class.class
+
+          return false unless argument_defined?
+          return false unless type_matches?
+          return false unless optional_matches?
+          return false unless default_matches?
+          return false unless context_matches?
+
+          true
+        end
+
+        def failure_message
+          return "expected #{@actual_class} to define argument :#{@name}" unless argument_defined?
+          return type_failure_message unless type_matches?
+          return optional_failure_message unless optional_matches?
+          return default_failure_message unless default_matches?
+          return context_failure_message unless context_matches?
+
+          ""
+        end
+
+        def failure_message_when_negated
+          "expected #{@actual_class} not to define argument :#{@name}"
+        end
+
+        def description
+          desc = "define argument :#{@name}"
+          desc += " with type #{@expected_type}" if @expected_type
+          desc += " as optional" if @expected_optional == true
+          desc += " as required" if @expected_optional == false
+          desc += " with default #{@expected_default.inspect}" if @check_default
+          desc += " with context" if @expected_context
+          desc
+        end
+
+        private
+
+        def argument_defined?
+          @actual_class.respond_to?(:arguments) && @actual_class.arguments.key?(@name)
+        end
+
+        def argument
+          @argument ||= @actual_class.arguments[@name]
+        end
+
+        def type_matches?
+          return true if @expected_type.nil?
+
+          # Access the type via instance variable since there's no public getter
+          actual_type = argument.instance_variable_get(:@type)
+          actual_type == @expected_type
+        end
+
+        def optional_matches?
+          return true if @expected_optional.nil?
+
+          argument.optional == @expected_optional
+        end
+
+        def default_matches?
+          return true unless @check_default
+
+          argument.default_exists && argument.default == @expected_default
+        end
+
+        def context_matches?
+          return true if @expected_context.nil?
+
+          argument.context == @expected_context
+        end
+
+        def type_failure_message
+          actual_type = argument.instance_variable_get(:@type)
+          "expected #{@actual_class} argument :#{@name} to have type #{@expected_type}, " \
+            "but it has type #{actual_type.inspect}"
+        end
+
+        def optional_failure_message
+          if @expected_optional
+            "expected #{@actual_class} argument :#{@name} to be optional, but it is required"
+          else
+            "expected #{@actual_class} argument :#{@name} to be required, but it is optional"
+          end
+        end
+
+        def default_failure_message
+          if argument.default_exists
+            "expected #{@actual_class} argument :#{@name} to have default #{@expected_default.inspect}, " \
+              "but it has default #{argument.default.inspect}"
+          else
+            "expected #{@actual_class} argument :#{@name} to have default #{@expected_default.inspect}, " \
+              "but no default is defined"
+          end
+        end
+
+        def context_failure_message
+          if @expected_context
+            "expected #{@actual_class} argument :#{@name} to have context flag, but it doesn't"
+          else
+            "expected #{@actual_class} argument :#{@name} not to have context flag, but it does"
+          end
+        end
+      end
+    end
+  end
+end