operandi 5.0.0

data/lib/ruby_lsp/operandi/indexing_enhancement.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module RubyLsp
+  module Operandi
+    class IndexingEnhancement < RubyIndexer::Enhancement
+      # DSL methods that generate getter, predicate, and setter methods
+      FIELD_DSL_METHODS = [:arg, :output].freeze
+
+      # ─────────────────────────────────────────────────────────────────────────
+      # Public API - Called by Ruby LSP indexer
+      # ─────────────────────────────────────────────────────────────────────────
+
+      # Called when the indexer encounters a method call node
+      # Detects `arg` and `output` DSL calls and registers the generated methods
+      def on_call_node_enter(node)
+        return unless @listener.current_owner
+        return unless FIELD_DSL_METHODS.include?(node.name)
+
+        field_name = extract_field_name(node)
+        return unless field_name
+
+        ruby_type = extract_ruby_type(node)
+        register_field_methods(field_name, node.location, ruby_type)
+      end
+
+      def on_call_node_leave(node); end
+
+      private
+
+      # ─────────────────────────────────────────────────────────────────────────
+      # Field Extraction
+      # ─────────────────────────────────────────────────────────────────────────
+
+      # Extract the field name from the first argument (symbol)
+      # Example: `arg :user` → "user"
+      def extract_field_name(node)
+        arguments = node.arguments&.arguments
+        return unless arguments&.any?
+
+        first_arg = arguments.first
+        return unless first_arg.is_a?(Prism::SymbolNode)
+
+        first_arg.value
+      end
+
+      # ─────────────────────────────────────────────────────────────────────────
+      # Type Resolution
+      # ─────────────────────────────────────────────────────────────────────────
+
+      # Extract and resolve the Ruby type from the `type:` keyword argument
+      # Returns the mapped Ruby type string or the original type if no mapping exists
+      def extract_ruby_type(node)
+        type_node = find_type_value_node(node)
+        return unless type_node
+
+        resolve_to_ruby_type(type_node)
+      end
+
+      # Find the value node for the `type:` keyword argument
+      def find_type_value_node(node)
+        arguments = node.arguments&.arguments
+        return unless arguments
+
+        keyword_hash = arguments.find { |arg| arg.is_a?(Prism::KeywordHashNode) }
+        return unless keyword_hash
+
+        # NOTE: Prism's SymbolNode#value returns a String, not a Symbol
+        type_element = keyword_hash.elements.find do |element|
+          element.is_a?(Prism::AssocNode) &&
+            element.key.is_a?(Prism::SymbolNode) &&
+            element.key.value == "type"
+        end
+
+        type_element&.value
+      end
+
+      # Resolve a Prism type node to a Ruby type string
+      # Handles constants, constant paths, and method chains
+      def resolve_to_ruby_type(node)
+        type_string = node_to_constant_string(node)
+        return unless type_string
+
+        map_to_ruby_type(type_string) || type_string
+      end
+
+      # Convert a Prism node to its constant string representation
+      def node_to_constant_string(node)
+        case node
+        when Prism::ConstantReadNode
+          node.name.to_s
+        when Prism::ConstantPathNode
+          build_constant_path(node)
+        when Prism::CallNode
+          # Handle method chains like Types::String.constrained(...) or Types::Array.of(...)
+          extract_receiver_constant(node)
+        end
+      end
+
+      # Build a full constant path string from nested ConstantPathNodes
+      # Example: MyApp::Config
+      def build_constant_path(node)
+        parts = []
+        current = node
+
+        while current.is_a?(Prism::ConstantPathNode)
+          parts.unshift(current.name.to_s)
+          current = current.parent
+        end
+
+        parts.unshift(current.name.to_s) if current.is_a?(Prism::ConstantReadNode)
+        parts.join("::")
+      end
+
+      # Extract the receiver constant from a method call chain
+      # Example: SomeClass.method(...) → "SomeClass"
+      def extract_receiver_constant(node)
+        receiver = node.receiver
+        return unless receiver
+
+        case receiver
+        when Prism::ConstantReadNode, Prism::ConstantPathNode
+          node_to_constant_string(receiver)
+        when Prism::CallNode
+          extract_receiver_constant(receiver)
+        end
+      end
+
+      # ─────────────────────────────────────────────────────────────────────────
+      # Type Mapping
+      # ─────────────────────────────────────────────────────────────────────────
+
+      # Map a type string to its corresponding Ruby type
+      # Uses custom mappings from config if available
+      def map_to_ruby_type(type_string)
+        mappings = effective_type_mappings
+        return nil if mappings.empty?
+
+        # Direct mapping lookup (custom mappings take precedence)
+        return mappings[type_string] if mappings.key?(type_string)
+
+        # Handle parameterized types
+        base_type = type_string.split(".").first
+        mappings[base_type]
+      end
+
+      # Returns the effective type mappings from config
+      def effective_type_mappings
+        return {} unless defined?(::Operandi)
+        return {} unless ::Operandi.respond_to?(:config)
+
+        custom_mappings = ::Operandi.config&.ruby_lsp_type_mappings
+        return {} if custom_mappings.nil?
+
+        custom_mappings
+      rescue NoMethodError
+        {}
+      end
+
+      # ─────────────────────────────────────────────────────────────────────────
+      # Method Registration
+      # ─────────────────────────────────────────────────────────────────────────
+
+      # Register all three generated methods for a field (getter, predicate, setter)
+      def register_field_methods(field_name, location, ruby_type)
+        register_getter(field_name, location, ruby_type)
+        register_predicate(field_name, location)
+        register_setter(field_name, location, ruby_type)
+      end
+
+      def register_getter(field_name, location, ruby_type)
+        @listener.add_method(
+          field_name.to_s,
+          location,
+          no_params_signature,
+          comments: return_type_comment(ruby_type),
+        )
+      end
+
+      def register_predicate(field_name, location)
+        @listener.add_method(
+          "#{field_name}?",
+          location,
+          no_params_signature,
+          comments: "@return [Boolean]",
+        )
+      end
+
+      def register_setter(field_name, location, ruby_type)
+        @listener.add_method(
+          "#{field_name}=",
+          location,
+          value_param_signature,
+          comments: setter_comment(ruby_type),
+        )
+      end
+
+      # ─────────────────────────────────────────────────────────────────────────
+      # Signatures & Comments
+      # ─────────────────────────────────────────────────────────────────────────
+
+      def no_params_signature
+        [RubyIndexer::Entry::Signature.new([])]
+      end
+
+      def value_param_signature
+        [RubyIndexer::Entry::Signature.new([
+          RubyIndexer::Entry::RequiredParameter.new(name: :value),
+        ])]
+      end
+
+      def return_type_comment(ruby_type)
+        return nil unless ruby_type
+
+        "@return [#{ruby_type}]"
+      end
+
+      def setter_comment(ruby_type)
+        return "@param value the value to set" unless ruby_type
+
+        "@param value [#{ruby_type}] the value to set\n@return [#{ruby_type}]"
+      end
+    end
+  end
+end

data/lib/tapioca/dsl/compilers/operandi.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+return unless defined?(Tapioca::Dsl::Compiler)
+
+module Tapioca
+  module Dsl
+    module Compilers
+      # Tapioca DSL compiler for Operandi
+      #
+      # Generates RBI signatures for methods automatically defined by the
+      # `arg`/`argument` and `output` DSL macros in operandi.
+      #
+      # For each argument and output, three methods are generated:
+      # - Getter: `def name` - returns the value
+      # - Predicate: `def name?` - returns boolean
+      # - Setter: `def name=` (private) - sets the value
+      #
+      # Additionally, typed inner classes are generated:
+      # - `Arguments` - T::Struct representing all service arguments
+      # - `Outputs` - T::Struct representing all service outputs
+      #
+      # @example Service definition
+      #   class CreateUser < Operandi::Base
+      #     arg :name, type: String
+      #     arg :email, type: String, optional: true
+      #     arg :role, type: [Symbol, String]
+      #
+      #     output :user, type: User
+      #   end
+      #
+      # @example Generated RBI
+      #   class CreateUser
+      #     class Arguments < T::Struct
+      #       prop :name, ::String
+      #       prop :email, T.nilable(::String), default: nil
+      #       prop :role, T.any(::Symbol, ::String)
+      #     end
+      #
+      #     class Outputs < T::Struct
+      #       prop :user, ::User
+      #     end
+      #
+      #     sig { returns(Arguments) }
+      #     def arg; end
+      #
+      #     sig { returns(Outputs) }
+      #     def output; end
+      #
+      #     sig { returns(String) }
+      #     def name; end
+      #
+      #     sig { returns(T::Boolean) }
+      #     def name?; end
+      #
+      #     sig { returns(T.nilable(String)) }
+      #     def email; end
+      #
+      #     sig { returns(T::Boolean) }
+      #     def email?; end
+      #
+      #     sig { returns(T.any(Symbol, String)) }
+      #     def role; end
+      #
+      #     sig { returns(T::Boolean) }
+      #     def role?; end
+      #
+      #     sig { returns(User) }
+      #     def user; end
+      #
+      #     sig { returns(T::Boolean) }
+      #     def user?; end
+      #
+      #     private
+      #
+      #     sig { params(value: String).returns(String) }
+      #     def name=(value); end
+      #
+      #     # ... other setters
+      #   end
+      class Operandi < Compiler # rubocop:disable Metrics/ClassLength
+        extend T::Sig
+
+        ConstantType = type_member { { fixed: T.class_of(::Operandi::Base) } }
+        CONFIG_TYPE = "T::Hash[T.any(::String, ::Symbol), T.untyped]"
+        SERVICE_OR_CONFIG_TYPE = "T.any(::Operandi::Base, #{CONFIG_TYPE})".freeze
+
+        class << self
+          extend T::Sig
+
+          sig { override.returns(T::Enumerable[Module]) }
+          def gather_constants
+            all_classes.select do |klass|
+              klass < ::Operandi::Base && klass.name && klass != ::Operandi::Base
+            end
+          end
+        end
+
+        sig { override.void }
+        def decorate
+          root.create_path(constant) do |klass|
+            # Generate class methods (.run, .run!, .with)
+            generate_class_methods(klass)
+
+            # Generate typed inner classes for arguments and outputs
+            generate_arguments_type(klass)
+            generate_outputs_type(klass)
+
+            # Generate argument methods
+            constant.arguments.each_value do |field|
+              generate_field_methods(klass, field)
+            end
+
+            # Generate output methods
+            constant.outputs.each_value do |field|
+              generate_field_methods(klass, field)
+            end
+          end
+        end
+
+        private
+
+        sig { params(klass: RBI::Scope).void }
+        def generate_class_methods(klass)
+          generate_run_method(klass)
+          generate_run_bang_method(klass)
+          generate_with_method(klass)
+        end
+
+        sig { params(klass: RBI::Scope).void }
+        def generate_arguments_type(klass)
+          return if constant.arguments.empty?
+
+          generate_struct_class(klass, "Arguments", constant.arguments)
+          klass.create_method("arg", return_type: "Arguments")
+        end
+
+        sig { params(klass: RBI::Scope).void }
+        def generate_outputs_type(klass)
+          return if constant.outputs.empty?
+
+          generate_struct_class(klass, "Outputs", constant.outputs)
+          klass.create_method("output", return_type: "Outputs")
+        end
+
+        sig { params(klass: RBI::Scope).void }
+        def generate_run_method(klass)
+          klass.create_method(
+            "run",
+            parameters: generate_argument_parameters,
+            return_type: "T.attached_class",
+            class_method: true,
+          )
+        end
+
+        sig { params(klass: RBI::Scope).void }
+        def generate_run_bang_method(klass)
+          klass.create_method(
+            "run!",
+            parameters: generate_argument_parameters,
+            return_type: "T.attached_class",
+            class_method: true,
+          )
+        end
+
+        sig { params(klass: RBI::Scope).void }
+        def generate_with_method(klass)
+          klass.create_method(
+            "with",
+            parameters: [create_param("service_or_config", type: SERVICE_OR_CONFIG_TYPE),
+                         create_opt_param("config", type: CONFIG_TYPE, default: "{}"),],
+            return_type: "T.self_type",
+            class_method: true,
+          )
+        end
+
+        sig { returns(T::Array[T.untyped]) }
+        def generate_argument_parameters
+          # Sort required params before optional (Sorbet requirement)
+          constant.arguments
+            .sort_by { |_, field| field.optional || field.default_exists ? 1 : 0 }
+            .map { |name, field| create_argument_param(name, field) }
+        end
+
+        sig { params(name: Symbol, field: ::Operandi::Settings::Field).returns(T.untyped) }
+        def create_argument_param(name, field)
+          ruby_type = resolve_argument_input_type(field)
+          return create_kw_param(name.to_s, type: ruby_type) unless field.optional || field.default_exists
+
+          param_type = field.optional ? as_nilable_type(ruby_type) : ruby_type
+          create_kw_opt_param(name.to_s, type: param_type, default: format_default_value(field))
+        end
+
+        sig { params(field: ::Operandi::Settings::Field).returns(String) }
+        def format_default_value(field)
+          return "nil" if field.optional && !field.default_exists
+          return "T.unsafe(nil)" unless field.default_exists
+
+          format_literal_default(field.default)
+        end
+
+        sig { params(default: T.untyped).returns(String) }
+        def format_literal_default(default)
+          case default
+          when String, Symbol then default.inspect
+          when Numeric, TrueClass, FalseClass then default.to_s
+          when NilClass then "nil"
+          when Hash then default.empty? ? "{}" : "T.unsafe(nil)"
+          when Array then default.empty? ? "[]" : "T.unsafe(nil)"
+          else "T.unsafe(nil)" # Proc and other complex types
+          end
+        end
+
+        sig { params(field: ::Operandi::Settings::Field).returns(String) }
+        def resolve_argument_input_type(field)
+          type = field.instance_variable_get(:@type)
+          return resolve_enum_argument_input_type(type) if sorbet_enum_class?(type)
+
+          resolve_type(field)
+        end
+
+        sig { params(type: T.class_of(T::Enum)).returns(String) }
+        def resolve_enum_argument_input_type(type)
+          any_type_for([ruby_type_for_class(type), *enum_serialized_types(type)])
+        end
+
+        sig { params(type: T.class_of(T::Enum)).returns(T::Array[String]) }
+        def enum_serialized_types(type)
+          type.values.map { |value| ruby_type_for_class(value.serialize.class) }.uniq
+        rescue StandardError
+          []
+        end
+
+        sig { params(types: T::Array[String]).returns(String) }
+        def any_type_for(types)
+          resolved_types = types.uniq
+          return resolved_types.first if resolved_types.size == 1
+
+          "T.any(#{resolved_types.join(', ')})"
+        end
+
+        sig { params(klass: RBI::Scope, field: ::Operandi::Settings::Field).void }
+        def generate_field_methods(klass, field)
+          name = field.name.to_s
+          ruby_type = resolve_type(field)
+          return_type = field.optional ? as_nilable_type(ruby_type) : ruby_type
+
+          # Getter
+          klass.create_method(name, return_type: return_type)
+
+          # Predicate
+          klass.create_method("#{name}?", return_type: "T::Boolean")
+
+          # Setter (private)
+          klass.create_method(
+            "#{name}=",
+            parameters: [create_param("value", type: return_type)],
+            return_type: return_type,
+            visibility: RBI::Private.new,
+          )
+        end
+
+        sig { params(field: ::Operandi::Settings::Field).returns(String) }
+        def resolve_type(field)
+          type = field.instance_variable_get(:@type)
+          return "T.untyped" unless type
+
+          if type.is_a?(Array)
+            resolve_array_type(type)
+          elsif sorbet_type?(type)
+            resolve_sorbet_type(type)
+          elsif type.is_a?(Class) || type.is_a?(Module)
+            ruby_type_for_class(type)
+          else
+            "T.untyped"
+          end
+        end
+
+        sig { params(types: T::Array[T.untyped]).returns(String) }
+        def resolve_array_type(types)
+          resolved_types = types.map do |t|
+            if t.is_a?(Class) || t.is_a?(Module)
+              ruby_type_for_class(t)
+            else
+              "T.untyped"
+            end
+          end.uniq
+
+          return resolved_types.first if resolved_types.size == 1
+
+          # Check if this is a boolean type (TrueClass + FalseClass)
+          if resolved_types.sort == ["::FalseClass", "::TrueClass"]
+            "T::Boolean"
+          else
+            "T.any(#{resolved_types.join(', ')})"
+          end
+        end
+
+        sig { params(klass: T.any(Class, Module)).returns(String) }
+        def ruby_type_for_class(klass)
+          name = klass.name
+          return "T.untyped" unless name
+
+          # Handle boolean types specially
+          if klass == TrueClass
+            "::TrueClass"
+          elsif klass == FalseClass
+            "::FalseClass"
+          else
+            "::#{name}"
+          end
+        end
+
+        sig { params(type: T.untyped).returns(T::Boolean) }
+        def sorbet_type?(type)
+          defined?(T::Types::Base) && type.is_a?(T::Types::Base)
+        end
+
+        sig { params(type: T.untyped).returns(T::Boolean) }
+        def sorbet_enum_class?(type)
+          return false unless type.is_a?(Class)
+
+          (defined?(T::Enum) && type < T::Enum) || serializable_enum_class?(type)
+        end
+
+        sig { params(type: Class).returns(T::Boolean) }
+        def serializable_enum_class?(type)
+          type.respond_to?(:try_deserialize) &&
+            type.respond_to?(:values) &&
+            type.values.any? &&
+            type.values.all? { |value| value.respond_to?(:serialize) }
+        rescue StandardError
+          false
+        end
+
+        sig { params(type: T.untyped).returns(String) }
+        def resolve_sorbet_type(type)
+          type.name || "T.untyped"
+        end
+
+        sig { params(type: String).returns(String) }
+        def as_nilable_type(type)
+          # Don't double-wrap nilable types
+          return type if type.start_with?("T.nilable(")
+          return type if type == "T.untyped"
+
+          "T.nilable(#{type})"
+        end
+
+        sig do
+          params(
+            klass: RBI::Scope,
+            class_name: String,
+            fields: T::Hash[Symbol, ::Operandi::Settings::Field],
+          ).void
+        end
+        def generate_struct_class(klass, class_name, fields)
+          return if fields.empty?
+
+          klass.create_class(class_name, superclass_name: "T::Struct") do |struct_klass|
+            fields.each_value do |field|
+              generate_struct_prop(struct_klass, field)
+            end
+          end
+        end
+
+        sig { params(struct_klass: RBI::Scope, field: ::Operandi::Settings::Field).void }
+        def generate_struct_prop(struct_klass, field)
+          name = field.name.to_s
+          ruby_type = resolve_type(field)
+          prop_type = field.optional ? as_nilable_type(ruby_type) : ruby_type
+          default_value = format_default_value(field) if field.optional || field.default_exists
+
+          struct_klass << RBI::TStructProp.new(name, prop_type, default: default_value)
+        end
+      end
+    end
+  end
+end

data/operandi.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/operandi/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "operandi"
+  spec.version       = Operandi::VERSION
+  spec.authors       = ["Andrew Kodkod"]
+  spec.email         = ["andrew@kodkod.me"]
+
+  spec.summary       = "Robust service architecture for Ruby/Rails applications"
+  spec.description   = "Operandi is a simple yet powerful way to organize business logic in Ruby applications. Build services that are easy to test, maintain, and understand." # rubocop:disable Layout/LineLength
+  spec.homepage      = "https://operandi-docs.vercel.app/"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/akodkod/operandi"
+  spec.metadata["changelog_uri"] = "https://github.com/akodkod/operandi/blob/master/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+
+  spec.bindir                            = "exe"
+  spec.executables                       = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths                     = ["lib"]
+  spec.metadata["rubygems_mfa_required"] = "true"
+end