light-services 3.2.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eaf377a62c2b05d82860527f64df11bb2239745d2e3b6ab1bc060cddc153effc
-  data.tar.gz: 86eb6a64e0744e6fe2f80b1b4fc06e9d38a740911f88c2b076da9e9a2aab082b
+  metadata.gz: 3f1c7874fc2ac069ac686f0b12895567c76c7005523dc0c1b841781f73ab3988
+  data.tar.gz: 4b41b830919ac007ec7740b1a84ca7d8a39682d9623fd9fd9085546e384391a3
 SHA512:
-  metadata.gz: b11918fed0617837cd922a9c7c2181a855844d359bce30aa7f523a828e77e3605522cff64440cf200f90732cb17bbee901305a01920bde54a3cb4777b748a760
-  data.tar.gz: aa78896f8cf22b7e2cf17853700bbe347d0dd364409ee4033064d7c4c5fa57d9377620e5ab6b29473cf15c2894e29b189aa8634e7d71ffda9ad2ca6fa6fce792
+  metadata.gz: eac0742e9f253e03b5e1cb58619798fc81b4f3139df62311c9350d4f3f1a13264dc4ad74af14e84033fa66137fbe31b390f95056783a83151ec76527c0590bc3
+  data.tar.gz: 45a9a709c76c57032c8ae71bc8fa31e32fee3aebe8e82a8c1265480c400ab2a724cfc9dc9d3572a830ff78a03235cfd94a95f782c4c92750db5d5f0d9f83bd6f

data/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
-## 3.2.0 (2025-12-14)
+## 3.3.0 (2025-12-15)
+
+### Added
+
+- Sorbet and Tapioca support for `arg` and `output`
+
+## 3.2.1 (2025-12-15)
+
+### Added
+
+- Add RuboCop cop `ReservedName`
+
+## 3.2.0 (2025-12-15)
 
 ### Added
 
@@ -12,7 +24,7 @@
 
 - Service runs steps with `always: true` after `fail_immediately!` was called
 
-## 3.1.2 (2025-12-13)
+## 3.1.2 (2025-12-14)
 
 ### Added
 
@@ -22,7 +34,7 @@
 
 - Split `config.require_type` into `config.require_arg_type` and `config.require_output_type`
 
-## 3.1.1 (2025-12-13)
+## 3.1.1 (2025-12-14)
 
 ### Added
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    light-services (3.2.0)
+    light-services (3.3.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -18,6 +18,7 @@ Light Services is a simple yet powerful way to organize business logic in Ruby a
 - 🧪 **RSpec Matchers**: Built-in RSpec matchers for expressive service tests
 - 🌐 **Framework Agnostic**: Compatible with Rails, Hanami, or any Ruby framework
 - 🧩 **Modularity**: Isolate and test your services with ease
+- 🔷 **Sorbet & Tapioca**: Full support for Sorbet type checking and Tapioca DSL generation
 - ✅ **100% Test Coverage**: Thoroughly tested and reliable
 - ⚔️ **Battle-Tested**: In production use since 2017
 

data/docs/README.md

@@ -16,6 +16,7 @@ Light Services is a simple yet powerful way to organize business logic in Ruby a
 - 🔍 **RuboCop Integration**: Custom cops to enforce best practices at lint time
 - 🌐 **Framework Agnostic**: Compatible with Rails, Hanami, or any Ruby framework
 - 🧩 **Modularity**: Isolate and test your services with ease
+- 🔷 **Sorbet & Tapioca**: Full support for Sorbet type checking and Tapioca DSL generation
 - ✅ **100% Test Coverage**: Thoroughly tested and reliable
 - ⚔️ **Battle-Tested**: In production use since 2017
 

data/docs/SUMMARY.md

@@ -19,6 +19,7 @@
 * [Rails Generators](generators.md)
 * [RuboCop Integration](rubocop.md)
 * [Ruby LSP Integration](ruby-lsp.md)
+* [Tapioca / Sorbet Integration](tapioca.md)
 
 ## Examples
 

data/docs/tapioca.md

@@ -0,0 +1,200 @@
+# Tapioca / Sorbet Integration
+
+Light Services provides a [Tapioca](https://github.com/Shopify/tapioca) DSL compiler that generates RBI signatures for methods automatically created by the `arg` and `output` DSL macros. This enables full Sorbet type checking for your services.
+
+## Features
+
+When you use the `arg` or `output` keywords, Light Services dynamically generates methods at runtime:
+
+```ruby
+class CreateUser < ApplicationService
+  arg :name, type: String
+  arg :email, type: String, optional: true
+  arg :role, type: [Symbol, String]
+  
+  output :user, type: User
+end
+```
+
+The Tapioca compiler generates RBI signatures for these methods:
+
+```rbi
+# sorbet/rbi/dsl/create_user.rbi
+# typed: true
+
+class CreateUser
+  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
+
+  sig { params(value: T.nilable(String)).returns(T.nilable(String)) }
+  def email=(value); end
+
+  sig { params(value: T.any(Symbol, String)).returns(T.any(Symbol, String)) }
+  def role=(value); end
+
+  sig { params(value: User).returns(User) }
+  def user=(value); end
+end
+```
+
+## Setup
+
+### 1. Install Tapioca
+
+Add Tapioca to your Gemfile:
+
+```ruby
+group :development do
+  gem "tapioca", require: false
+end
+```
+
+Then run:
+
+```bash
+bundle install
+bundle exec tapioca init
+```
+
+### 2. Generate RBI Files
+
+The Light Services compiler is automatically discovered by Tapioca. Generate RBI files with:
+
+```bash
+bundle exec tapioca dsl
+```
+
+This will create RBI files in `sorbet/rbi/dsl/` for all your services.
+
+### 3. Re-generate After Changes
+
+After adding or modifying `arg`/`output` declarations, regenerate the RBI files:
+
+```bash
+bundle exec tapioca dsl LightServices
+```
+
+## Type Mappings
+
+### Ruby Types
+
+Standard Ruby types are mapped directly:
+
+| Ruby Type | Sorbet Type |
+|-----------|-------------|
+| `String` | `::String` |
+| `Integer` | `::Integer` |
+| `Float` | `::Float` |
+| `Hash` | `::Hash` |
+| `Array` | `::Array` |
+| `Symbol` | `::Symbol` |
+| `User` (custom) | `::User` |
+
+### Boolean Types
+
+Boolean types are mapped to `T::Boolean`:
+
+```ruby
+arg :active, type: [TrueClass, FalseClass]
+# Generates: sig { returns(T::Boolean) }
+```
+
+### Union Types
+
+Multiple types create union types:
+
+```ruby
+arg :id, type: [String, Integer]
+# Generates: sig { returns(T.any(::String, ::Integer)) }
+```
+
+### Optional Types
+
+Optional arguments/outputs are wrapped in `T.nilable`:
+
+```ruby
+arg :nickname, type: String, optional: true
+# Generates: sig { returns(T.nilable(::String)) }
+```
+
+### Dry-Types
+
+If you use [dry-types](https://dry-rb.org/gems/dry-types/), they are mapped to their primitive Ruby types:
+
+| Dry Type | Sorbet Type |
+|----------|-------------|
+| `Types::String` | `::String` |
+| `Types::Strict::String` | `::String` |
+| `Types::Integer` | `::Integer` |
+| `Types::Bool` | `T::Boolean` |
+| `Types::Array` | `::Array` |
+| `Types::Hash` | `::Hash` |
+| `Types::Date` | `::Date` |
+| `Types::Time` | `::Time` |
+| `Types::DateTime` | `::DateTime` |
+| `Types::Decimal` | `::BigDecimal` |
+| `Types::Any` | `T.untyped` |
+
+Parameterized dry-types (e.g., `Types::Array.of(String)`) are mapped to their base type.
+
+## Generated Methods
+
+For each `arg` or `output`, three methods are generated:
+
+| Method | Return Type | Visibility |
+|--------|-------------|------------|
+| `name` | The declared type | public |
+| `name?` | `T::Boolean` | public |
+| `name=` | The declared type | **private** |
+
+## Inheritance
+
+The compiler handles inherited arguments and outputs. If a child service inherits from a parent, the RBI will include methods for both parent and child fields.
+
+## Troubleshooting
+
+### RBI files not generated
+
+Ensure Light Services is properly loaded in your application. The compiler only runs if `Light::Services::Base` is defined.
+
+### Types showing as `T.untyped`
+
+This happens when:
+- No `type:` option is specified for the argument/output
+- The type cannot be resolved (e.g., undefined constant)
+
+### Custom type mappings
+
+If you need custom dry-types mappings, you can extend the `DRY_TYPE_MAPPINGS` constant in the compiler or open an issue to add common mappings.
+
+## See Also
+
+- [Ruby LSP Integration](ruby-lsp.md) - Editor integration without Sorbet
+- [Arguments](arguments.md) - Full `arg` DSL documentation  
+- [Outputs](outputs.md) - Full `output` DSL documentation

data/lib/light/services/rubocop/cop/light_services/reserved_name.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../../../../../light/services/constants"
+
+module RuboCop
+  module Cop
+    module LightServices
+      # Ensures that `arg`, `step`, and `output` declarations do not use reserved names
+      # that would conflict with Light::Services methods.
+      #
+      # @example
+      #   # bad
+      #   arg :errors, type: Array
+      #   arg :outputs, type: Hash
+      #   step :call
+      #   output :success?, type: [TrueClass, FalseClass]
+      #
+      #   # good
+      #   arg :validation_errors, type: Array
+      #   arg :result_outputs, type: Hash
+      #   step :execute
+      #   output :succeeded, type: [TrueClass, FalseClass]
+      #
+      class ReservedName < Base
+        include RuboCop::Cop::RangeHelp
+
+        MSG = "`%<name>s` is a reserved name and cannot be used as %<field_type>s. " \
+              "It conflicts with Light::Services methods."
+
+        SEVERITY = :error
+
+        RESTRICT_ON_SEND = [:arg, :step, :output].freeze
+
+        FIELD_TYPE_NAMES = {
+          arg: "an argument",
+          step: "a step",
+          output: "an output",
+        }.freeze
+
+        # @!method dsl_call?(node)
+        def_node_matcher :dsl_call?, <<~PATTERN
+          (send nil? ${:arg :step :output} (sym $_) ...)
+        PATTERN
+
+        def on_send(node)
+          dsl_call?(node) do |method_name, name|
+            return unless Light::Services::ReservedNames::ALL.include?(name)
+
+            field_type = FIELD_TYPE_NAMES[method_name]
+            add_offense(node, message: format(MSG, name: name, field_type: field_type), severity: SEVERITY)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/light/services/rubocop.rb

@@ -10,4 +10,5 @@ require_relative "rubocop/cop/light_services/missing_private_keyword"
 require_relative "rubocop/cop/light_services/no_direct_instantiation"
 require_relative "rubocop/cop/light_services/output_type_required"
 require_relative "rubocop/cop/light_services/prefer_fail_method"
+require_relative "rubocop/cop/light_services/reserved_name"
 require_relative "rubocop/cop/light_services/step_method_exists"

data/lib/light/services/version.rb

@@ -2,6 +2,6 @@
 
 module Light
   module Services
-    VERSION = "3.2.0"
+    VERSION = "3.3.0"
   end
 end

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

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+return unless defined?(Tapioca::Dsl::Compiler)
+
+module Tapioca
+  module Dsl
+    module Compilers
+      # Tapioca DSL compiler for Light::Services
+      #
+      # Generates RBI signatures for methods automatically defined by the
+      # `arg`/`argument` and `output` DSL macros in light-services.
+      #
+      # 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
+      #
+      # @example Service definition
+      #   class CreateUser < Light::Services::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
+      #     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 LightServices < Compiler
+        extend T::Sig
+
+        # Default type mappings for common dry-types to their underlying Ruby types
+        DRY_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" => "T::Boolean",
+          "Types::Strict::Bool" => "T::Boolean",
+          "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" => "T.untyped",
+        }.freeze
+
+        ConstantType = type_member { { fixed: T.class_of(::Light::Services::Base) } }
+
+        class << self
+          extend T::Sig
+
+          sig { override.returns(T::Enumerable[Module]) }
+          def gather_constants
+            all_classes.select do |klass|
+              klass < ::Light::Services::Base && klass.name && klass != ::Light::Services::Base
+            end
+          end
+        end
+
+        sig { override.void }
+        def decorate
+          arguments = constant.arguments
+          outputs = constant.outputs
+
+          return if arguments.empty? && outputs.empty?
+
+          root.create_path(constant) do |klass|
+            # Generate argument methods
+            arguments.each_value do |field|
+              generate_field_methods(klass, field)
+            end
+
+            # Generate output methods
+            outputs.each_value do |field|
+              generate_field_methods(klass, field)
+            end
+          end
+        end
+
+        private
+
+        sig { params(klass: RBI::Scope, field: ::Light::Services::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: ::Light::Services::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 dry_type?(type)
+            resolve_dry_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)
+            elsif dry_type?(t)
+              resolve_dry_type(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 dry_type?(type)
+          return false unless defined?(Dry::Types::Type)
+
+          type.is_a?(Dry::Types::Type)
+        end
+
+        sig { params(type: T.untyped).returns(String) }
+        def resolve_dry_type(type)
+          type_string = type.to_s
+
+          # Direct mapping lookup
+          return DRY_TYPE_MAPPINGS[type_string] if DRY_TYPE_MAPPINGS.key?(type_string)
+
+          # Handle parameterized types: Types::Array.of(...) → Types::Array
+          base_type = type_string.split(".").first
+          return DRY_TYPE_MAPPINGS[base_type] if DRY_TYPE_MAPPINGS.key?(base_type)
+
+          # Try to infer from primitive
+          infer_from_primitive(type)
+        end
+
+        sig { params(type: T.untyped).returns(String) }
+        def infer_from_primitive(type)
+          return "T.untyped" unless type.respond_to?(:primitive)
+
+          primitive = type.primitive
+          return "T.untyped" unless primitive.is_a?(Class) || primitive.is_a?(Module)
+
+          ruby_type_for_class(primitive)
+        rescue StandardError
+          "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
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: light-services
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.3.0
 platform: ruby
 authors:
 - Andrew Kodkod
@@ -55,6 +55,7 @@ files:
 - docs/ruby-lsp.md
 - docs/service-rendering.md
 - docs/steps.md
+- docs/tapioca.md
 - docs/testing.md
 - lib/generators/light_services/install/USAGE
 - lib/generators/light_services/install/install_generator.rb
@@ -99,6 +100,7 @@ files:
 - 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/prefer_fail_method.rb
+- lib/light/services/rubocop/cop/light_services/reserved_name.rb
 - lib/light/services/rubocop/cop/light_services/step_method_exists.rb
 - lib/light/services/settings/field.rb
 - lib/light/services/settings/step.rb
@@ -107,6 +109,7 @@ files:
 - lib/ruby_lsp/light_services/addon.rb
 - lib/ruby_lsp/light_services/definition.rb
 - lib/ruby_lsp/light_services/indexing_enhancement.rb
+- lib/tapioca/dsl/compilers/light_services.rb
 - light-services.gemspec
 homepage: https://light-services-docs.vercel.app/
 licenses: