light-services 2.2.1 → 3.1.0

data/lib/ruby_lsp/light_services/indexing_enhancement.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module RubyLsp
+  module LightServices
+    class IndexingEnhancement < RubyIndexer::Enhancement # rubocop:disable Metrics/ClassLength
+      # DSL methods that generate getter, predicate, and setter methods
+      FIELD_DSL_METHODS = [:arg, :output].freeze
+
+      # Default type mappings for common dry-types to their underlying Ruby types
+      # These can be extended via Light::Services.config.ruby_lsp_type_mappings
+      DEFAULT_TYPE_MAPPINGS = {
+        "Types::String" => "String",
+        "Types::Strict::String" => "String",
+        "Types::Coercible::String" => "String",
+        "Types::Integer" => "Integer",
+        "Types::Strict::Integer" => "Integer",
+        "Types::Coercible::Integer" => "Integer",
+        "Types::Float" => "Float",
+        "Types::Strict::Float" => "Float",
+        "Types::Coercible::Float" => "Float",
+        "Types::Decimal" => "BigDecimal",
+        "Types::Strict::Decimal" => "BigDecimal",
+        "Types::Coercible::Decimal" => "BigDecimal",
+        "Types::Bool" => "TrueClass | FalseClass",
+        "Types::Strict::Bool" => "TrueClass | FalseClass",
+        "Types::True" => "TrueClass",
+        "Types::Strict::True" => "TrueClass",
+        "Types::False" => "FalseClass",
+        "Types::Strict::False" => "FalseClass",
+        "Types::Array" => "Array",
+        "Types::Strict::Array" => "Array",
+        "Types::Hash" => "Hash",
+        "Types::Strict::Hash" => "Hash",
+        "Types::Symbol" => "Symbol",
+        "Types::Strict::Symbol" => "Symbol",
+        "Types::Coercible::Symbol" => "Symbol",
+        "Types::Date" => "Date",
+        "Types::Strict::Date" => "Date",
+        "Types::DateTime" => "DateTime",
+        "Types::Strict::DateTime" => "DateTime",
+        "Types::Time" => "Time",
+        "Types::Strict::Time" => "Time",
+        "Types::Nil" => "NilClass",
+        "Types::Strict::Nil" => "NilClass",
+        "Types::Any" => "Object",
+      }.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: Types::Strict::String
+      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: Types::String.constrained(format: /@/) → "Types::String"
+      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) merged with defaults
+      def map_to_ruby_type(type_string)
+        mappings = effective_type_mappings
+
+        # Direct mapping lookup (custom mappings take precedence)
+        return mappings[type_string] if mappings.key?(type_string)
+
+        # Handle parameterized types: Types::Array.of(...) → Types::Array
+        base_type = type_string.split(".").first
+        mappings[base_type]
+      end
+
+      # Returns the effective type mappings (defaults + custom from config)
+      # Custom mappings take precedence over defaults
+      def effective_type_mappings
+        return DEFAULT_TYPE_MAPPINGS unless defined?(Light::Services)
+        return DEFAULT_TYPE_MAPPINGS unless Light::Services.respond_to?(:config)
+
+        custom_mappings = Light::Services.config&.ruby_lsp_type_mappings
+        return DEFAULT_TYPE_MAPPINGS if custom_mappings.nil? || custom_mappings.empty?
+
+        DEFAULT_TYPE_MAPPINGS.merge(custom_mappings)
+      rescue NoMethodError
+        DEFAULT_TYPE_MAPPINGS
+      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/light-services.gemspec

@@ -8,11 +8,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Andrew Kodkod"]
   spec.email         = ["andrew@kodkod.me"]
 
-  spec.summary       = "Robust service architecture for Ruby frameworks"
-  spec.description   = "Robust service architecture for Ruby frameworks"
+  spec.summary       = "Robust service architecture for Ruby/Rails applications"
+  spec.description   = "Light Services 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://light-services-docs.vercel.app/"
   spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
@@ -26,10 +26,8 @@ Gem::Specification.new do |spec|
     `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.bindir                            = "exe"
+  spec.executables                       = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths                     = ["lib"]
   spec.metadata["rubygems_mfa_required"] = "true"
-
-  spec.add_dependency "benchmark", ">= 0.5"
 end

metadata

@@ -1,29 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: light-services
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 3.1.0
 platform: ruby
 authors:
 - Andrew Kodkod
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: benchmark
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.5'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.5'
-description: Robust service architecture for Ruby frameworks
+dependencies: []
+description: Light Services is a simple yet powerful way to organize business logic
+  in Ruby applications. Build services that are easy to test, maintain, and understand.
 email:
 - andrew@kodkod.me
 executables: []
@@ -38,6 +25,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -46,22 +34,76 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/arguments.md
+- docs/best-practices.md
+- docs/callbacks.md
+- docs/concepts.md
+- docs/configuration.md
+- docs/context.md
+- docs/crud.md
+- docs/errors.md
+- docs/generators.md
+- docs/outputs.md
+- docs/pundit-authorization.md
+- docs/quickstart.md
+- docs/readme.md
+- docs/recipes.md
+- docs/rubocop.md
+- docs/ruby-lsp.md
+- docs/service-rendering.md
+- docs/steps.md
+- docs/summary.md
+- docs/testing.md
+- lib/generators/light_services/install/USAGE
+- lib/generators/light_services/install/install_generator.rb
+- lib/generators/light_services/install/templates/application_service.rb.tt
+- lib/generators/light_services/install/templates/application_service_spec.rb.tt
+- lib/generators/light_services/install/templates/initializer.rb.tt
+- lib/generators/light_services/service/USAGE
+- lib/generators/light_services/service/service_generator.rb
+- lib/generators/light_services/service/templates/service.rb.tt
+- lib/generators/light_services/service/templates/service_spec.rb.tt
 - lib/light/services.rb
 - lib/light/services/base.rb
 - lib/light/services/base_with_context.rb
-- lib/light/services/class_based_collection/base.rb
-- lib/light/services/class_based_collection/mount.rb
-- lib/light/services/collection/arguments.rb
-- lib/light/services/collection/base.rb
-- lib/light/services/collection/outputs.rb
+- lib/light/services/callbacks.rb
+- lib/light/services/collection.rb
+- lib/light/services/concerns/execution.rb
+- lib/light/services/concerns/parent_service.rb
+- lib/light/services/concerns/state_management.rb
 - lib/light/services/config.rb
+- lib/light/services/constants.rb
+- lib/light/services/dsl/arguments_dsl.rb
+- lib/light/services/dsl/outputs_dsl.rb
+- lib/light/services/dsl/steps_dsl.rb
+- lib/light/services/dsl/validation.rb
 - lib/light/services/exceptions.rb
 - lib/light/services/message.rb
 - lib/light/services/messages.rb
-- lib/light/services/settings/argument.rb
-- lib/light/services/settings/output.rb
+- lib/light/services/rspec.rb
+- lib/light/services/rspec/matchers/define_argument.rb
+- lib/light/services/rspec/matchers/define_output.rb
+- lib/light/services/rspec/matchers/define_step.rb
+- lib/light/services/rspec/matchers/execute_step.rb
+- lib/light/services/rspec/matchers/have_error_on.rb
+- lib/light/services/rspec/matchers/have_warning_on.rb
+- lib/light/services/rspec/matchers/trigger_callback.rb
+- lib/light/services/rubocop.rb
+- lib/light/services/rubocop/cop/light_services/argument_type_required.rb
+- lib/light/services/rubocop/cop/light_services/condition_method_exists.rb
+- lib/light/services/rubocop/cop/light_services/deprecated_methods.rb
+- lib/light/services/rubocop/cop/light_services/dsl_order.rb
+- lib/light/services/rubocop/cop/light_services/missing_private_keyword.rb
+- lib/light/services/rubocop/cop/light_services/no_direct_instantiation.rb
+- lib/light/services/rubocop/cop/light_services/output_type_required.rb
+- lib/light/services/rubocop/cop/light_services/step_method_exists.rb
+- lib/light/services/settings/field.rb
 - lib/light/services/settings/step.rb
+- lib/light/services/utils.rb
 - lib/light/services/version.rb
+- lib/ruby_lsp/light_services/addon.rb
+- lib/ruby_lsp/light_services/definition.rb
+- lib/ruby_lsp/light_services/indexing_enhancement.rb
 - light-services.gemspec
 homepage: https://light-services-docs.vercel.app/
 licenses:
@@ -79,7 +121,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -88,5 +130,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Robust service architecture for Ruby frameworks
+summary: Robust service architecture for Ruby/Rails applications
 test_files: []

data/lib/light/services/class_based_collection/base.rb

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-# Create class based collections for storing arguments settings, steps settings and outputs settings
-#
-# General functionality:
-#   1. Collection automatically loads data from parent classes
-#   2. It's possible to redefine items if needed (e.g. arguments)
-#   3. We can add items into collection after or before another items
-#
-module Light
-  module Services
-    module ClassBasedCollection
-      class Base
-        # TODO: Add `prepend: true`
-        def initialize(item_class, allow_redefine)
-          @item_class = item_class
-          @allow_redefine = allow_redefine
-          @collection = {}
-        end
-
-        def add(klass, name, opts = {})
-          @collection[klass] ||= all_from_superclass(klass)
-
-          validate_name!(klass, name)
-          validate_opts!(klass, name, opts)
-
-          item = @item_class.new(name, klass, opts)
-
-          if opts[:before] || opts[:after]
-            insert_item(klass, name, opts, item)
-          else
-            @collection[klass][name] = item
-          end
-        end
-
-        def find_index(klass, name)
-          index = @collection[klass].keys.index(name)
-
-          return index if index
-
-          # TODO: Update `NoStepError` because it maybe not only step
-          raise Light::Services::NoStepError, "Cannot find #{@item_class} `#{name}` in service #{klass}"
-        end
-
-        def remove(klass, name)
-          @collection[klass] ||= all_from_superclass(klass)
-          @collection[klass].delete(name)
-        end
-
-        def all(klass)
-          @collection[klass] || all_from_superclass(klass)
-        end
-
-        private
-
-        def all_from_superclass(klass)
-          if klass.superclass <= Light::Services::Base
-            all(klass.superclass).dup
-          else
-            {}
-          end
-        end
-
-        def validate_name!(klass, name)
-          if !@allow_redefine && all(klass).key?(name)
-            raise Light::Services::Error, "#{@item_class} with name `#{name}` already exists in service #{klass}"
-          end
-        end
-
-        def validate_opts!(klass, name, opts)
-          if opts[:before] && opts[:after]
-            raise Light::Services::Error, "You cannot specify `before` and `after` " \
-                                          "for #{@item_class} `#{name}` in service #{klass} at the same time"
-          end
-        end
-
-        def insert_item(klass, name, opts, item)
-          index = find_index(klass, opts[:before] || opts[:after])
-          index += 1 unless opts[:before]
-
-          @collection[klass] = @collection[klass].to_a.insert(index, [name, item]).to_h
-        end
-      end
-    end
-  end
-end

data/lib/light/services/class_based_collection/mount.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-# This class allows to mount class based collections to service objects
-#
-# Usage:
-#
-#   mount_class_based_collection :steps,     klass: Settings::Step,     shortcut: :step
-#   mount_class_based_collection :outputs,   klass: Settings::Output,   shortcut: :output
-#   mount_class_based_collection :arguments, klass: Settings::Argument, shortcut: :arg, allow_redefine: true
-#
-module Light
-  module Services
-    module ClassBasedCollection
-      module Mount
-        def mount_class_based_collection(collection_name, item_class:, shortcut:, allow_redefine: false)
-          class_variable_set(:"@@#{collection_name}", ClassBasedCollection::Base.new(item_class, allow_redefine))
-
-          define_singleton_method shortcut do |item_name, opts = {}|
-            class_variable_get(:"@@#{collection_name}").add(self, item_name, opts)
-          end
-
-          define_singleton_method :"remove_#{shortcut}" do |item_name|
-            class_variable_get(:"@@#{collection_name}").remove(self, item_name)
-          end
-
-          define_singleton_method collection_name do
-            class_variable_get(:"@@#{collection_name}").all(self)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/light/services/collection/arguments.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-# Collection to store, merge and validate arguments
-module Light
-  module Services
-    module Collection
-      class Arguments < Base
-        def extend_with_context(args)
-          settings_collection.each do |name, settings|
-            next if !settings.context || args.key?(name) || !key?(name)
-
-            args[settings.name] = get(name)
-          end
-
-          args
-        end
-
-        def validate!
-          settings_collection.each do |name, settings|
-            next if settings.optional && (!key?(name) || get(name).nil?)
-
-            settings.validate_type!(get(name))
-          end
-        end
-
-        private
-
-        def settings_collection
-          @instance.class.arguments
-        end
-      end
-    end
-  end
-end

data/lib/light/services/collection/base.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-# Collection to store arguments and outputs values
-module Light
-  module Services
-    module Collection
-      class Base
-        # Includes
-        extend Forwardable
-
-        # Settings
-        def_delegators :@storage, :key?, :to_h
-
-        def initialize(instance, storage = {})
-          @instance = instance
-          @storage = storage
-
-          return if storage.is_a?(Hash)
-
-          raise Light::Services::ArgTypeError, "#{instance.class} - arguments must be a Hash"
-        end
-
-        def set(key, value)
-          @storage[key] = value
-        end
-
-        def get(key)
-          @storage[key]
-        end
-
-        def [](key)
-          get(key)
-        end
-
-        def []=(key, value)
-          set(key, value)
-        end
-
-        def load_defaults
-          settings_collection.each do |name, settings|
-            next if !settings.default_exists || key?(name)
-
-            if settings.default.is_a?(Proc)
-              set(name, @instance.instance_exec(&settings.default))
-            else
-              set(name, deep_dup(settings.default))
-            end
-          end
-        end
-
-        private
-
-        def deep_dup(object)
-          Marshal.load(Marshal.dump(object))
-        end
-      end
-    end
-  end
-end

data/lib/light/services/collection/outputs.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-# Collection to store outputs values
-module Light
-  module Services
-    module Collection
-      class Outputs < Base
-        private
-
-        def settings_collection
-          @instance.class.outputs
-        end
-      end
-    end
-  end
-end