servactory 2.16.1 → 3.0.0.rc1

data/lib/generators/servactory/{templates/services/application_service/base.rb → install/templates/application_service/base.rb.tt}

@@ -1,32 +1,41 @@
 # frozen_string_literal: true
 
-module ApplicationService
-  class Base
-    include Servactory::DSL
+module <%= namespace %>
+  class Base < Servactory::Base
+<% unless minimal? -%>
 
     # More information: https://servactory.com/guide/extensions
-    # include Servactory::DSL.with_extensions(
-    #   ApplicationService::Extensions::YourExtension::DSL
-    # )
+    # extensions do
+    #   before :actions, <%= namespace %>::Extensions::Authorization::DSL
+    #   after :actions, <%= namespace %>::Extensions::Publishable::DSL
+    # end
 
-    fail_on! ActiveRecord::RecordInvalid
+    # fail_on! ActiveRecord::RecordInvalid
+    # fail_on!(
+    #   CustomException,
+    #   with: ->(exception:) { ... }
+    # )
 
     # More information: https://servactory.com/guide/configuration
+<% end -%>
     configuration do
-      input_exception_class ApplicationService::Exceptions::Input
-      internal_exception_class ApplicationService::Exceptions::Internal
-      output_exception_class ApplicationService::Exceptions::Output
+      input_exception_class <%= namespace %>::Exceptions::Input
+      internal_exception_class <%= namespace %>::Exceptions::Internal
+      output_exception_class <%= namespace %>::Exceptions::Output
 
-      failure_class ApplicationService::Exceptions::Failure
+      failure_class <%= namespace %>::Exceptions::Failure
 
-      result_class ApplicationService::Result
+      result_class <%= namespace %>::Result
+<% unless minimal? -%>
 
       # input_option_helpers(
       #   [
       #     Servactory::ToolKit::DynamicOptions::Format.use,
       #     Servactory::ToolKit::DynamicOptions::Min.use,
       #     Servactory::ToolKit::DynamicOptions::Max.use,
-      #     ApplicationService::DynamicOptions::CustomEq.use
+      #     Servactory::ToolKit::DynamicOptions::MultipleOf.use,
+      #     Servactory::ToolKit::DynamicOptions::Target.use,
+      #     <%= namespace %>::DynamicOptions::CustomEq.use
       #   ]
       # )
 
@@ -35,7 +44,9 @@ module ApplicationService
       #     Servactory::ToolKit::DynamicOptions::Format.use,
       #     Servactory::ToolKit::DynamicOptions::Min.use,
       #     Servactory::ToolKit::DynamicOptions::Max.use,
-      #     ApplicationService::DynamicOptions::CustomEq.use
+      #     Servactory::ToolKit::DynamicOptions::MultipleOf.use,
+      #     Servactory::ToolKit::DynamicOptions::Target.use,
+      #     <%= namespace %>::DynamicOptions::CustomEq.use
       #   ]
       # )
 
@@ -44,14 +55,14 @@ module ApplicationService
       #     Servactory::ToolKit::DynamicOptions::Format.use,
       #     Servactory::ToolKit::DynamicOptions::Min.use,
       #     Servactory::ToolKit::DynamicOptions::Max.use,
-      #     ApplicationService::DynamicOptions::CustomEq.use
+      #     Servactory::ToolKit::DynamicOptions::MultipleOf.use,
+      #     Servactory::ToolKit::DynamicOptions::Target.use,
+      #     <%= namespace %>::DynamicOptions::CustomEq.use
       #   ]
       # )
 
       # collection_mode_class_names [ActiveRecord::Relation]
 
-      # hash_mode_class_names [CustomHash]
-
       # action_shortcuts(
       #   %i[assign build create save],
       #   {
@@ -64,9 +75,8 @@ module ApplicationService
 
       # action_aliases %i[do_it!]
 
-      # i18n_root_key :servactory
-
       # predicate_methods_enabled false
+<% end -%>
     end
   end
 end

data/lib/generators/servactory/{templates/services/application_service/exceptions.rb → install/templates/application_service/exceptions.rb.tt}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module ApplicationService
+module <%= namespace %>
   module Exceptions
     class Input < Servactory::Exceptions::Input; end
     class Output < Servactory::Exceptions::Output; end

data/lib/generators/servactory/{templates/services/application_service/result.rb → install/templates/application_service/result.rb.tt}

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-module ApplicationService
+module <%= namespace %>
   class Result < Servactory::Result; end
 end

data/lib/generators/servactory/rspec/USAGE

@@ -0,0 +1,46 @@
+Description:
+    Generates an RSpec spec file for a Servactory service.
+
+Usage:
+    rails generate servactory:rspec NAME [inputs] [options]
+
+Arguments:
+    NAME           The name of the service (e.g., Users::Create, ProcessOrder)
+    inputs         Input attributes with optional types (e.g., email:string, user:User)
+
+Options:
+    --skip-pending       Skip pending placeholder
+    --call-method=METHOD Primary call method: call or call! (default: call!)
+    --path=PATH          Path to service files (default: app/services)
+                         Spec path is auto-derived: app/X -> spec/X, lib/X -> spec/X
+
+Type Formats:
+    Lowercase types are normalized to Ruby classes:
+        string -> String, integer -> Integer, boolean -> [TrueClass, FalseClass]
+
+    Capitalized Ruby class names are preserved as-is:
+        String, Integer, Hash, Array
+
+    Custom types (models, enums, Structs) are preserved:
+        User, Admin::Role, Billing::PaymentStatus
+
+    Untyped inputs default to String.
+
+Examples:
+    rails generate servactory:rspec Users::Create email:string name:string
+        Creates spec/services/users/create_spec.rb with typed inputs
+
+    rails generate servactory:rspec Users::Create email:String name:String
+        Creates spec/services/users/create_spec.rb with Ruby class types
+
+    rails generate servactory:rspec ProcessOrder user:User event:Event
+        Creates spec with custom model/class type inputs
+
+    rails generate servactory:rspec Users::Create --path=lib/my_gem/services
+        Creates spec/my_gem/services/users/create_spec.rb for gem/library use
+
+    rails generate servactory:rspec ProcessOrder --call-method=call
+        Creates spec using .call instead of .call!
+
+    rails generate servactory:rspec CacheData --skip-pending
+        Creates spec without pending placeholder

data/lib/generators/servactory/rspec/rspec_generator.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module Servactory
+  module Generators
+    class RspecGenerator < Servactory::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      argument :inputs, type: :array, default: [], banner: "name:type"
+
+      class_option :call_method,
+                   type: :string,
+                   default: "call!",
+                   enum: %w[call call!],
+                   desc: "Primary call method (call or call!)"
+
+      class_option :path,
+                   type: :string,
+                   default: "app/services",
+                   desc: "Path to service files (specs auto-generated to spec/...)"
+
+      class_option :skip_pending,
+                   type: :boolean,
+                   default: false,
+                   desc: "Skip pending placeholder"
+
+      def create_spec_file
+        template "service_spec.rb.tt", spec_file_path
+      end
+
+      private
+
+      def spec_file_path
+        "#{specs_path}/#{file_path}_spec.rb"
+      end
+
+      def specs_path
+        # Convert services path to specs path:
+        # app/services → spec/services
+        # lib/foo → spec/foo
+        # engines/core/app/services → engines/core/spec/services
+        # engines/admin/lib/services → engines/admin/spec/services
+        path = services_path
+
+        # Handle Rails engine paths first
+        return path.sub(%r{/app/}, "/spec/") if path.match?(%r{^engines/[^/]+/app/})
+
+        return path.sub(%r{/lib/}, "/spec/") if path.match?(%r{^engines/[^/]+/lib/})
+
+        # Standard app/ and lib/ paths
+        path
+          .sub(%r{^app/}, "spec/")
+          .sub(%r{^lib/}, "spec/")
+      end
+
+      def services_path
+        options[:path]
+      end
+
+      def call_method
+        options[:call_method]
+      end
+
+      def skip_pending?
+        options[:skip_pending]
+      end
+
+      def inputs_with_examples
+        parsed_inputs.map do |input|
+          input.merge(example: example_value_for_type(input[:type]))
+        end
+      end
+
+      def example_value_for_type(type_string) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+        case type_string
+        when "Integer" then "1"
+        when "Float" then "1.0"
+        when "TrueClass", "[TrueClass, FalseClass]" then "true"
+        when "FalseClass" then "false"
+        when "Array" then "[]"
+        when "Hash" then "{}"
+        when "Symbol" then ":example"
+        when "Date" then "Date.current"
+        when "DateTime" then "DateTime.current"
+        when "Time" then "Time.current"
+        when "NilClass" then "nil"
+        when "BigDecimal" then 'BigDecimal("1.0")'
+        else
+          '"Some value"'
+        end
+      end
+    end
+  end
+end

data/lib/generators/servactory/rspec/templates/service_spec.rb.tt

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+RSpec.describe <%= class_name %>, type: :service do
+<% unless skip_pending? -%>
+  pending "add some examples to (or delete) #{__FILE__}"
+
+<% end -%>
+  describe ".<%= call_method %>" do
+    subject(:perform) { described_class.<%= call_method %>(**attributes) }
+
+<% if inputs_with_examples.any? -%>
+    let(:attributes) do
+      {
+<% inputs_with_examples.each_with_index do |input, index| -%>
+        <%= input[:name] %>: <%= input[:name] %><%= index < inputs_with_examples.size - 1 ? ',' : '' %>
+<% end -%>
+      }
+    end
+
+<% inputs_with_examples.each do |input| -%>
+    let(:<%= input[:name] %>) { <%= input[:example] %> }
+<% end -%>
+<% else -%>
+    let(:attributes) do
+      {
+        # TODO: Add input attributes
+      }
+    end
+<% end -%>
+<% if inputs_with_examples.any? -%>
+
+    describe "validations" do
+      describe "inputs" do
+<% inputs_with_examples.each do |input| -%>
+        it do
+          expect { perform }.to(
+            have_input(:<%= input[:name] %>)
+              .valid_with(attributes)
+              .type(<%= input[:type] %>)
+              .required
+          )
+        end
+
+<% end -%>
+      end
+    end
+<% end -%>
+
+    describe "and the data required for work is also valid" do
+      it { expect(perform).to be_success_service }
+    end
+
+    describe "but the data required for work is invalid" do
+      # Provide a reason why the data is invalid and then use this:
+      # it { expect(perform).to be_failure_service }
+    end
+  end
+end

data/lib/generators/servactory/service/USAGE

@@ -0,0 +1,51 @@
+Description:
+    Generates a new Servactory service class.
+
+Usage:
+    rails generate servactory:service NAME [inputs] [options]
+
+Arguments:
+    NAME           The name of the service (e.g., Users::Create, ProcessOrder)
+    inputs         Input attributes with optional types (e.g., email:string, user:User)
+
+Options:
+    --base-class=CLASS    Base class for the service (default: ApplicationService::Base)
+    --skip-output         Skip default output declaration
+    --path=PATH           Path to generate service files (default: app/services)
+
+Type Formats:
+    Lowercase types are normalized to Ruby classes:
+        string → String, integer → Integer, boolean → [TrueClass, FalseClass]
+
+    Capitalized Ruby class names are preserved as-is:
+        String, Integer, Hash, Array
+
+    Custom types (models, enums, Structs) are preserved:
+        User, Admin::Role, Billing::PaymentStatus
+
+    Untyped inputs default to String.
+
+Examples:
+    rails generate servactory:service Users::Create
+        Creates app/services/users/create.rb with default structure
+
+    rails generate servactory:service Users::Create --path=lib/my_gem/services
+        Creates lib/my_gem/services/users/create.rb for gem/library use
+
+    rails generate servactory:service Users::Create email:string name:string
+        Creates service with typed inputs (lowercase types normalized to Ruby classes)
+
+    rails generate servactory:service Users::Create email:String name:String
+        Creates service with typed inputs (capitalized Ruby class names)
+
+    rails generate servactory:service ProcessOrder user:User event:Event
+        Creates service with custom model/class type inputs
+
+    rails generate servactory:service ProcessOrder role:Admin::Users::Role
+        Creates service with nested namespace type
+
+    rails generate servactory:service SendEmail recipient
+        Creates service with untyped input (defaults to String)
+
+    rails generate servactory:service CacheData key:String --skip-output
+        Creates service without default output declaration

data/lib/generators/servactory/service/service_generator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module Servactory
+  module Generators
+    class ServiceGenerator < Servactory::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      argument :inputs, type: :array, default: [], banner: "name:type"
+
+      class_option :base_class,
+                   type: :string,
+                   default: "ApplicationService::Base",
+                   desc: "Base class for the service"
+
+      class_option :path,
+                   type: :string,
+                   default: "app/services",
+                   desc: "Path to generate service files"
+
+      class_option :skip_output,
+                   type: :boolean,
+                   default: false,
+                   desc: "Skip default output declaration"
+
+      def create_service
+        template "service.rb.tt", service_file_path
+      end
+
+      private
+
+      def service_file_path
+        "#{services_path}/#{file_path}.rb"
+      end
+
+      def services_path
+        options[:path]
+      end
+
+      def base_class_name
+        options[:base_class]
+      end
+
+      def skip_output?
+        options[:skip_output]
+      end
+
+      def input_declarations
+        parsed_inputs.map do |input|
+          "input :#{input[:name]}, type: #{input[:type]}"
+        end
+      end
+    end
+  end
+end

data/lib/generators/servactory/service/templates/service.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < <%= base_class_name %>
+<% input_declarations.each do |declaration| -%>
+  <%= declaration %>
+<% end -%>
+<% unless skip_output? -%>
+
+  output :data, type: String
+<% end -%>
+
+  make :assign_data
+
+  private
+
+  def assign_data
+    # TODO: Implement service logic
+<% unless skip_output? -%>
+    outputs.data = "done"
+<% end -%>
+  end
+end

data/lib/servactory/actions/collection.rb

@@ -2,15 +2,70 @@
 
 module Servactory
   module Actions
+    # Mutable collection manager for Action objects.
+    #
+    # ## Purpose
+    #
+    # Stores Action objects and provides query methods to retrieve actions
+    # sorted by position. Wraps a Set for unique action storage with
+    # position-based ordering capabilities.
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # actions = Servactory::Actions::Collection.new
+    # actions << Action.new(:first, position: 1)
+    # actions << Action.new(:second, position: 2)
+    #
+    # actions.sorted_by_position  # => Collection with sorted actions
+    # actions.empty?              # => false
+    # actions.size                # => 2
+    # ```
+    #
+    # ## Integration
+    #
+    # Used by Servactory::Actions::Stages::Stage to store actions within
+    # a stage, and by Servactory::Actions::Tools::Runner to execute
+    # actions in the correct order.
     class Collection
       extend Forwardable
 
-      def_delegators :@collection, :<<, :each, :to_h, :sort_by
+      # @!method <<(action)
+      #   Adds an action to the collection.
+      #   @param action [Action] The action to add
+      #   @return [Set] The updated collection
+      # @!method each
+      #   Iterates over all actions in the collection.
+      #   @yield [Action] Each action in the collection
+      # @!method to_h
+      #   Converts collection to a hash.
+      #   @return [Hash] Hash representation
+      # @!method sort_by
+      #   Sorts actions by the given block.
+      #   @yield [Action] Each action for comparison
+      #   @return [Array<Action>] Sorted array of actions
+      # @!method size
+      #   Returns the number of actions in the collection.
+      #   @return [Integer] Number of actions
+      # @!method empty?
+      #   Checks if the collection is empty.
+      #   @return [Boolean] true if no actions registered
+      def_delegators :@collection, :<<, :each, :to_h, :sort_by, :size, :empty?
 
+      # Creates a new actions collection.
+      #
+      # @param collection [Set] Initial collection of actions (default: empty Set)
       def initialize(collection = Set.new)
         @collection = collection
       end
 
+      # Returns a new collection with actions sorted by position.
+      #
+      # @return [Collection] New collection with actions in position order
+      #
+      # @example
+      #   sorted = actions.sorted_by_position
+      #   sorted.each { |action| puts action.position }
       def sorted_by_position
         Collection.new(sort_by(&:position))
       end

data/lib/servactory/actions/dsl.rb

@@ -41,9 +41,9 @@ module Servactory
 
           instance_eval(&block)
 
-          @current_stage = nil
+          collection_of_stages << @current_stage unless @current_stage.actions.empty?
 
-          nil
+          @current_stage = nil
         end
 
         def wrap_in(wrapper)
@@ -75,15 +75,15 @@ module Servactory
         def make(name, position: nil, **options)
           position = position.presence || next_position
 
-          current_stage = @current_stage.presence || Stages::Stage.new(position:)
-
-          current_stage.actions << Action.new(
-            name,
-            position:,
-            **options
-          )
-
-          collection_of_stages << current_stage
+          if @current_stage.present?
+            # Inside stage block - just add action, stage will be added at block end
+            @current_stage.actions << Action.new(name, position:, **options)
+          else
+            # Outside stage block - create new stage and add to collection
+            new_stage = Stages::Stage.new(position:)
+            new_stage.actions << Action.new(name, position:, **options)
+            collection_of_stages << new_stage
+          end
         end
 
         def method_missing(name, *args, &block)

data/lib/servactory/actions/tools/rules.rb

@@ -56,7 +56,7 @@ module Servactory
         end
 
         def raise_message_with!(formatted_text)
-          raise @context.class.config.failure_class.new(
+          raise @context.config.failure_class.new(
             type: :base,
             message: @context.send(:servactory_service_info).translate(
               "methods.cannot_be_overwritten",