operandi 5.0.0

data/lib/operandi/settings/field.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Operandi
+  module Settings
+    # Stores configuration for a single argument or output field.
+    # Created automatically when using the `arg` or `output` DSL methods.
+    class Field
+      # @return [Symbol] the field name
+      attr_reader :name
+
+      # @return [Boolean] true if a default value was specified
+      attr_reader :default_exists
+
+      # @return [Object, Proc, nil] the default value or proc
+      attr_reader :default
+
+      # @return [Boolean, nil] true if this is a context argument
+      attr_reader :context
+
+      # @return [Boolean, nil] true if nil values are allowed
+      attr_reader :optional
+
+      # Initialize a new field definition.
+      #
+      # @param name [Symbol] the field name
+      # @param service_class [Class] the service class this field belongs to
+      # @param opts [Hash] field options
+      # @option opts [Class, Array<Class>] :type type(s) to validate against
+      # @option opts [Boolean] :optional whether nil is allowed
+      # @option opts [Object, Proc] :default default value or proc
+      # @option opts [Boolean] :context whether to pass to child services
+      # @option opts [Symbol] :field_type :argument or :output
+      def initialize(name, service_class, opts = {})
+        @name = name
+        @service_class = service_class
+        @field_type = opts.delete(:field_type) || :argument
+
+        @type = opts.delete(:type)
+        @context = opts.delete(:context)
+        @default_exists = opts.key?(:default)
+        @default = opts.delete(:default)
+        @optional = opts.delete(:optional)
+
+        define_methods
+      end
+
+      # Validate a value against the field's type definition.
+      # Supports Ruby class types and Sorbet runtime types.
+      #
+      # @param value [Object] the value to validate
+      # @return [Object] the validated value
+      # @raise [ArgTypeError] if the value doesn't match the expected type
+      def validate_type!(value)
+        return value unless @type
+
+        if sorbet_type?(@type) || (sorbet_available? && plain_class_type?(@type))
+          validate_sorbet_type!(value)
+        else
+          validate_ruby_type!(value)
+          value
+        end
+      end
+
+      FIELD_TYPE_TO_IVAR = {
+        FieldTypes::ARGUMENT => :@arg,
+        FieldTypes::OUTPUT => :@output,
+      }.freeze
+
+      private
+
+      # Check if sorbet-runtime is available
+      def sorbet_available?
+        defined?(T::Types::Base)
+      end
+
+      # Check if the type is a plain Ruby class (not a Sorbet type)
+      def plain_class_type?(type)
+        type.is_a?(Class) || type.is_a?(Module)
+      end
+
+      # Check if the type is a Sorbet runtime type
+      def sorbet_type?(type)
+        return false unless defined?(T::Types::Base)
+
+        type.is_a?(T::Types::Base)
+      end
+
+      # Validate value against Sorbet runtime types
+      # Note: Sorbet types only validate, they do not coerce values
+      # Automatically coerces plain Ruby classes to Sorbet types when needed
+      # @return [Object] the original value if valid
+      # @raise [ArgTypeError] if the value doesn't match the expected type
+      def validate_sorbet_type!(value)
+        sorbet_type = sorbet_type?(@type) ? @type : T::Utils.coerce(@type)
+        return value if sorbet_type.valid?(value)
+
+        enum_value = deserialize_enum_argument(value)
+        return enum_value if enum_value && sorbet_type.valid?(enum_value)
+
+        message = "#{@service_class} #{@field_type} `#{@name}` expected #{sorbet_type.name}, " \
+                  "but got #{value.class} with value: #{value.inspect}"
+
+        raise Operandi::ArgTypeError.new(message, service_class: @service_class)
+      end
+
+      def deserialize_enum_argument(value)
+        return nil unless @field_type == FieldTypes::ARGUMENT
+        return nil unless sorbet_enum_class?(@type)
+
+        @type.try_deserialize(value)
+      end
+
+      def sorbet_enum_class?(type)
+        defined?(T::Enum) && type.is_a?(Class) && type < T::Enum
+      end
+
+      # Validate value against Ruby class types
+      def validate_ruby_type!(value)
+        return if [*@type].any? { |type| value.is_a?(type) }
+
+        raise Operandi::ArgTypeError.new(type_error_message(value), service_class: @service_class)
+      end
+
+      def type_error_message(value)
+        expected_types = [*@type].map(&:to_s).join(" or ")
+        "#{@service_class} #{@field_type} `#{@name}` must be #{expected_types}, \" \\
+            \"but got #{value.class} with value: #{value.inspect}"
+      end
+
+      def define_methods
+        name = @name
+        collection_instance_var = FIELD_TYPE_TO_IVAR.fetch(@field_type)
+
+        @service_class.define_method(@name) { instance_variable_get(collection_instance_var).get(name) }
+        @service_class.define_method(:"#{@name}?") { !!instance_variable_get(collection_instance_var).get(name) }
+        @service_class.define_method(:"#{@name}=") do |value|
+          instance_variable_get(collection_instance_var).set(name, value)
+        end
+        @service_class.send(:private, "#{@name}=")
+      end
+    end
+
+    # Aliases for backwards compatibility
+    Argument = Field
+    Output = Field
+  end
+end

data/lib/operandi/settings/step.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Operandi
+  module Settings
+    # Stores configuration for a single service step.
+    # Created automatically when using the `step` DSL method.
+    class Step
+      # @return [Symbol] the step name (method to call)
+      attr_reader :name
+
+      # @return [Boolean, nil] true if step runs even after errors/warnings
+      attr_reader :always
+
+      # Initialize a new step definition.
+      #
+      # @param name [Symbol] the step name (must match a method)
+      # @param service_class [Class] the service class this step belongs to
+      # @param opts [Hash] step options
+      # @option opts [Symbol, Proc] :if condition to run the step
+      # @option opts [Symbol, Proc] :unless condition to skip the step
+      # @option opts [Boolean] :always run even after errors/warnings
+      # @raise [Error] if both :if and :unless are specified
+      def initialize(name, service_class, opts = {})
+        @name = name
+        @service_class = service_class
+
+        @if     = opts[:if]
+        @unless = opts[:unless]
+        @always = opts[:always]
+
+        if @if && @unless
+          raise Operandi::Error, "#{service_class} `if` and `unless` cannot be specified " \
+                                 "for the step `#{name}` at the same time"
+        end
+      end
+
+      # Execute the step on the given service instance.
+      #
+      # @param instance [Base] the service instance
+      # @return [Boolean] true if the step was executed, false if skipped
+      # @raise [RuntimeError] if the step method is not defined
+      def run(instance) # rubocop:disable Naming/PredicateMethod
+        return false unless run?(instance)
+
+        unless instance.respond_to?(name, true)
+          available_steps = @service_class.steps.keys.join(", ")
+          message = "Step method `#{name}` is not defined in #{@service_class}. " \
+                    "Defined steps: [#{available_steps}]"
+          raise Operandi::RuntimeError.new(message, service: instance)
+        end
+
+        execute_with_callbacks(instance)
+        true
+      end
+
+      private
+
+      def execute_with_callbacks(instance)
+        errors_count_before = instance.errors.count
+
+        instance.run_callbacks(:before_step_run, instance, name)
+
+        instance.run_callbacks(:around_step_run, instance, name) do
+          instance.send(name)
+        end
+
+        instance.run_callbacks(:after_step_run, instance, name)
+
+        if instance.errors.count > errors_count_before
+          instance.run_callbacks(:on_step_failure, instance, name)
+        else
+          instance.run_callbacks(:on_step_success, instance, name)
+        end
+      rescue StandardError => e
+        instance.run_callbacks(:on_step_crash, instance, name, e)
+        raise e
+      end
+
+      def run?(instance)
+        return false if instance.stopped?
+
+        if @if
+          check_condition(@if, instance)
+        elsif @unless
+          !check_condition(@unless, instance)
+        else
+          true
+        end
+      end
+
+      def check_condition(condition, instance)
+        case condition
+        when Symbol
+          instance.send(condition)
+        when Proc
+          instance.instance_exec(&condition)
+        else
+          message = "#{@service_class} condition should be a Symbol or Proc " \
+                    "for the step `#{@name}` (currently: #{condition.class})"
+          raise Operandi::RuntimeError.new(message, service: instance)
+        end
+      end
+    end
+  end
+end

data/lib/operandi/utils.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Operandi
+  # Utility module providing helper methods for the Operandi library
+  module Utils
+    module_function
+
+    # Creates a deep copy of an object to prevent mutation of shared references.
+    #
+    # @param object [Object] the object to duplicate
+    # @return [Object] a deep copy of the object
+    #
+    # @example Deep duping a hash
+    #   original = { a: { b: 1 } }
+    #   copy = Utils.deep_dup(original)
+    #   copy[:a][:b] = 2
+    #   original[:a][:b] # => 1
+    #
+    # @example Deep duping an array
+    #   original = [[1, 2], [3, 4]]
+    #   copy = Utils.deep_dup(original)
+    #   copy[0] << 5
+    #   original[0] # => [1, 2]
+    #
+    def deep_dup(object)
+      # Use ActiveSupport's deep_dup if available (preferred for Rails apps)
+      return object.deep_dup if object.respond_to?(:deep_dup)
+
+      # Fallback to Marshal for objects that support serialization
+      Marshal.load(Marshal.dump(object))
+    rescue TypeError
+      # Last resort: use dup if available, otherwise return original
+      object.respond_to?(:dup) ? object.dup : object
+    end
+  end
+end

data/lib/operandi/version.rb

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

data/lib/operandi.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "operandi/config"
+require "operandi/version"
+require "operandi/exceptions"
+require "operandi/utils"
+require "operandi/callbacks"
+require "operandi/base"
+
+module Operandi
+end

data/lib/ruby_lsp/operandi/addon.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../../operandi/version"
+require_relative "indexing_enhancement"
+require_relative "definition"
+
+# Declare version compatibility without runtime dependency on ruby-lsp
+RubyLsp::Addon.depend_on_ruby_lsp!("~> 0.26")
+
+module RubyLsp
+  module Operandi
+    class Addon < ::RubyLsp::Addon
+      def activate(global_state, message_queue)
+        @global_state = global_state
+        @message_queue = message_queue
+      end
+
+      def deactivate; end
+
+      def name
+        "Ruby LSP Operandi"
+      end
+
+      def version
+        ::Operandi::VERSION
+      end
+
+      # Called on every "go to definition" request
+      # Provides navigation from step DSL symbols to their method definitions
+      def create_definition_listener(response_builder, uri, node_context, dispatcher)
+        return unless @global_state
+
+        Definition.new(response_builder, uri, node_context, @global_state.index, dispatcher)
+      end
+    end
+  end
+end

data/lib/ruby_lsp/operandi/definition.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module RubyLsp
+  module Operandi
+    class Definition
+      # Condition options that reference methods
+      CONDITION_OPTIONS = [:if, :unless].freeze
+
+      def initialize(response_builder, uri, node_context, index, dispatcher)
+        @response_builder = response_builder
+        @uri = uri
+        @node_context = node_context
+        @index = index
+
+        # Register for symbol nodes - this is what gets triggered when user clicks on :method_name
+        dispatcher.register(self, :on_symbol_node_enter)
+      end
+
+      # Called when cursor is on a symbol node (e.g., :validate in `step :validate`)
+      def on_symbol_node_enter(node)
+        # Check if this symbol is part of a step call by examining the call context
+        call_node = find_parent_step_call
+        return unless call_node
+
+        method_name = determine_method_name(node, call_node)
+        return unless method_name
+
+        find_and_append_method_location(method_name)
+      end
+
+      private
+
+      # Find the parent step call node from the node context
+      # The node_context.call_node returns the enclosing call if cursor is on an argument
+      def find_parent_step_call
+        call_node = @node_context.call_node
+        return unless call_node
+        return unless call_node.name == :step
+
+        call_node
+      end
+
+      # Determine which method name to look up based on where the symbol appears
+      # Returns nil if this symbol is not a method reference we should handle
+      def determine_method_name(symbol_node, call_node)
+        symbol_value = symbol_node.value.to_sym
+
+        # Check if this is the first argument (step method name)
+        first_arg = call_node.arguments&.arguments&.first
+        if first_arg.is_a?(Prism::SymbolNode) && first_arg.value.to_sym == symbol_value && same_location?(
+          first_arg,
+          symbol_node,
+        )
+          # Verify the symbol node location matches (same node, not just same value)
+          return symbol_value.to_s
+        end
+
+        # Check if this is a condition option (if: or unless:)
+        keyword_hash = find_keyword_hash(call_node)
+        return unless keyword_hash
+
+        CONDITION_OPTIONS.each do |option_name|
+          condition_symbol = find_symbol_option(keyword_hash, option_name)
+          next unless condition_symbol
+          next unless same_location?(condition_symbol, symbol_node)
+
+          return condition_symbol.value.to_s
+        end
+
+        nil
+      end
+
+      # Check if two nodes have the same location (are the same node)
+      def same_location?(node1, node2)
+        node1.location.start_offset == node2.location.start_offset &&
+          node1.location.end_offset == node2.location.end_offset
+      end
+
+      # Find the keyword hash in call arguments
+      def find_keyword_hash(node)
+        node.arguments&.arguments&.find { |arg| arg.is_a?(Prism::KeywordHashNode) }
+      end
+
+      # Find a symbol value for a specific option in the keyword hash
+      # Returns the SymbolNode if found and value is a symbol, nil otherwise
+      def find_symbol_option(keyword_hash, option_name)
+        element = keyword_hash.elements.find do |elem|
+          elem.is_a?(Prism::AssocNode) &&
+            elem.key.is_a?(Prism::SymbolNode) &&
+            elem.key.value.to_sym == option_name
+        end
+
+        return unless element
+        return unless element.value.is_a?(Prism::SymbolNode)
+
+        element.value
+      end
+
+      # Find method definition in index and append location to response
+      def find_and_append_method_location(method_name)
+        owner_name = @node_context.nesting.join("::")
+        return if owner_name.empty?
+
+        # Look up method entries in the index
+        method_entries = @index.resolve_method(method_name, owner_name)
+        return unless method_entries&.any?
+
+        method_entries.each { |entry| append_location(entry) }
+
+        true
+      end
+
+      def append_location(entry)
+        @response_builder << Interface::Location.new(
+          uri: URI::Generic.from_path(path: entry.file_path).to_s,
+          range: build_range(entry.location),
+        )
+      end
+
+      def build_range(location)
+        Interface::Range.new(
+          start: Interface::Position.new(
+            line: location.start_line - 1,
+            character: location.start_column,
+          ),
+          end: Interface::Position.new(
+            line: location.end_line - 1,
+            character: location.end_column,
+          ),
+        )
+      end
+    end
+  end
+end