yes-core 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3e28057d0c8b0fd6c0bc4f4692c55609b353258637320027efe1d2bcbb02841
-  data.tar.gz: fdb462463528fdbecf3df473f5c0f98601a8d301ec7e4d52f98ec0b2aabdc0f3
+  metadata.gz: 0a7213daeb56ae07a8921c83b912e83b7f9cd81f6d93d90a4394cbe07b7c9299
+  data.tar.gz: 58379a04830d2ba08c0ca4431d4e372ee8cc67f8445621d7143c61f1dc27ab9a
 SHA512:
-  metadata.gz: 415e51919c284f2207fbd6ee6dfd9a9427830a6f20ab88986a69b94c14c62b15a75d0fe19360d58088a3d4de8beec953fa78e69c180458874c1d639d677fd9e0
-  data.tar.gz: 85a8557a897a3c2d02b315bf1e637f2bd6837300bf65b71430c314d9a047b9663cf8d33cfaeb7a681ea2bb5eaaf645a4297e351c3304abd56c8026a03d978792
+  metadata.gz: f5ce8a14fb78e7c9bc1b11264e16a17f0cbdc0ef3dcbbd7175114a1c772097b67cb1226f359429a6be83900f26d0e911dd18df838aa9c9ad5a76cab5d999b889
+  data.tar.gz: 01de285d8c90f81625bdd1ff721877b87d23edad1949b1eb860ebd4fc0274c459fbbeb3080e6ecb678fa1cd0174b010b4eb4f146ff00d6e4bea4be935685bb08

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.3.0] - 2026-05-18
+
+- See root CHANGELOG.md for details.
+
+## [1.2.0] - 2026-04-30
+
+- See root CHANGELOG.md for details.
+
 ## [1.1.0] - 2026-04-28
 
 - See root CHANGELOG.md for details.

data/lib/yes/core/aggregate/dsl/class_name_convention.rb

@@ -43,6 +43,14 @@ module Yes
             "#{context}::#{aggregate}::Commands::#{name.to_s.camelize}::GuardEvaluator"
           end
 
+          def command_group_class_name(name)
+            "#{context}::#{aggregate}::CommandGroups::#{name.to_s.camelize}::Command"
+          end
+
+          def command_group_guard_evaluator_class_name(name)
+            "#{context}::#{aggregate}::CommandGroups::#{name.to_s.camelize}::GuardEvaluator"
+          end
+
           def state_updater_class_name(name)
             "#{context}::#{aggregate}::Commands::#{name.to_s.camelize}::StateUpdater"
           end

data/lib/yes/core/aggregate/dsl/class_resolvers/command_group/base.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module ClassResolvers
+          module CommandGroup
+            # Base class for command_group-related class resolvers.
+            #
+            # Mirrors {ClassResolvers::Command::Base} but binds to
+            # {CommandGroupData} instead of {CommandData}.
+            #
+            # @abstract Subclass and implement {ClassResolvers::Base#class_type},
+            #   {ClassResolvers::Base#class_name}, and
+            #   {ClassResolvers::Base#generate_class}.
+            class Base < ClassResolvers::Base
+              # @param command_group_data [Yes::Core::Aggregate::Dsl::CommandGroupData]
+              def initialize(command_group_data)
+                @command_group_data = command_group_data
+
+                super(command_group_data.context_name, command_group_data.aggregate_name)
+              end
+
+              private
+
+              attr_reader :command_group_data
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/class_resolvers/command_group/command.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module ClassResolvers
+          module CommandGroup
+            # Resolves or generates the Command class for an aggregate-DSL
+            # command group. The generated class is a {Yes::Core::Commands::CommandGroup}
+            # subclass carrying the group's identity (context, aggregate,
+            # group_name) and the ordered list of sub-command names.
+            class Command < Base
+              private
+
+              def class_type
+                :command_group
+              end
+
+              def class_name
+                command_group_data.name
+              end
+
+              def generate_class
+                group_name = command_group_data.name
+                ctx = command_group_data.context_name
+                agg = command_group_data.aggregate_name
+                sub_commands = command_group_data.sub_command_names.dup
+
+                Class.new(Yes::Core::Commands::CommandGroup).tap do |klass|
+                  klass.context = ctx
+                  klass.aggregate = agg
+                  klass.group_name = group_name
+                  klass.sub_command_names = sub_commands
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/class_resolvers/command_group/guard_evaluator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module ClassResolvers
+          module CommandGroup
+            # Resolves or generates the GuardEvaluator class for a command_group.
+            #
+            # Unlike the per-command resolver, no `:no_change` guard is
+            # auto-injected — command groups are intended to be lighter on
+            # guard checks and rely on whatever set of guards the user
+            # declares explicitly in the DSL block.
+            class GuardEvaluator < Base
+              private
+
+              def class_type
+                :command_group_guard_evaluator
+              end
+
+              def class_name
+                command_group_data.name
+              end
+
+              def generate_class
+                Class.new(Yes::Core::CommandHandling::GuardEvaluator)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/command_data.rb

@@ -12,7 +12,7 @@ module Yes
         class CommandData
           attr_reader :name, :context_name, :aggregate_name, :aggregate_class
           attr_accessor :event_name, :payload_attributes, :update_state_block, :guard_names, :authorizer_block,
-                        :encrypted_attributes
+                        :encrypted_attributes, :skip_default_guards
 
           # @param name [Symbol] The name of the command
           # @param aggregate_class [Class] The aggregate class this command belongs to
@@ -21,6 +21,7 @@ module Yes
           # @option options [String] :aggregate The aggregate name
           # @option options [String] :event_name The event name for the command
           # @option options [Hash] :payload_attributes The payload attributes for the command
+          # @option options [Array<Symbol>] :skip_default_guards Default guards (e.g. :not_removed) that should not be auto-applied
           def initialize(name, aggregate_class, options = {})
             @name = name
             @aggregate_class = aggregate_class
@@ -38,6 +39,9 @@ module Yes
 
             # Track encrypted attributes for event schema generation
             @encrypted_attributes = []
+
+            # Default guards to opt out of (e.g. :not_removed for the :remove command itself)
+            @skip_default_guards = options.delete(:skip_default_guards) || []
           end
 
           # Add a guard name to the list of guards

data/lib/yes/core/aggregate/dsl/command_group_data.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        # Data object that holds information about a command_group definition
+        # in an aggregate.
+        #
+        # @example
+        #   CommandGroupData.new(:create_apprenticeship, MyAggregate, context: 'Companies', aggregate: 'Apprenticeship')
+        class CommandGroupData
+          attr_reader :name, :context_name, :aggregate_name, :aggregate_class
+          attr_accessor :sub_command_names, :guard_names
+
+          # @param name [Symbol] the name of the command group
+          # @param aggregate_class [Class] the aggregate class the group belongs to
+          # @param options [Hash] additional options
+          # @option options [String] :context the context name
+          # @option options [String] :aggregate the aggregate name
+          def initialize(name, aggregate_class, options = {})
+            @name = name
+            @aggregate_class = aggregate_class
+            @context_name = options[:context]
+            @aggregate_name = options[:aggregate]
+            @sub_command_names = []
+            @guard_names = []
+          end
+
+          # @param name [Symbol] sub-command name to append (preserves order)
+          # @return [void]
+          def add_sub_command(name)
+            @sub_command_names << name
+          end
+
+          # @param name [Symbol] guard name to record on this group
+          # @return [void]
+          def add_guard(name)
+            @guard_names << name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/command_group_definer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        # Factory class that creates and defines command_groups on aggregates.
+        #
+        # Mirrors {CommandDefiner}. The DSL evaluator inside accepts two
+        # methods: `command :sub_command_name` to push a sub-command symbol,
+        # and `guard(name, error_extra: …) { … }` to register a group-level
+        # guard on the generated GuardEvaluator class.
+        #
+        # @example
+        #   group_data = CommandGroupData.new(:create_apprenticeship, MyAggregate,
+        #                                     context: 'Companies', aggregate: 'Apprenticeship')
+        #   CommandGroupDefiner.new(group_data).call do
+        #     command :assign_company
+        #     command :change_name
+        #
+        #     guard(:company_assigned) { company_id.present? }
+        #   end
+        class CommandGroupDefiner
+          # Raised when an unknown sub-command name is referenced.
+          class UnknownSubCommandError < Yes::Core::Error; end
+
+          attr_reader :command_group_data
+          private :command_group_data
+
+          # @param command_group_data [CommandGroupData]
+          def initialize(command_group_data)
+            @command_group_data = command_group_data
+          end
+
+          # Generates and registers all classes/methods for the command group.
+          #
+          # @yield Block for declaring sub-commands and guards
+          # @return [void]
+          def call(&block)
+            create_and_register_guard_evaluator
+            evaluate_dsl_block(&block) if block
+            create_and_register_command
+            define_aggregate_methods
+          end
+
+          private
+
+          def create_and_register_guard_evaluator
+            @guard_evaluator_class = ClassResolvers::CommandGroup::GuardEvaluator.new(command_group_data).call
+          end
+
+          def create_and_register_command
+            ClassResolvers::CommandGroup::Command.new(command_group_data).call
+          end
+
+          def define_aggregate_methods
+            MethodDefiners::CommandGroup::CommandGroup.new(command_group_data).call
+            MethodDefiners::CommandGroup::CanCommandGroup.new(command_group_data).call
+          end
+
+          def evaluate_dsl_block(&)
+            DslEvaluator.new(command_group_data, @guard_evaluator_class).instance_eval(&)
+          end
+
+          # DSL evaluator that backs the `command_group :name do … end` block.
+          class DslEvaluator
+            attr_reader :command_group_data, :guard_evaluator_class
+
+            def initialize(command_group_data, guard_evaluator_class)
+              @command_group_data = command_group_data
+              @guard_evaluator_class = guard_evaluator_class
+            end
+
+            # Declare a sub-command. Order is preserved as execution order.
+            #
+            # @param name [Symbol] the sub-command name (must match a command
+            #   declared on the same aggregate)
+            # @return [void]
+            def command(name)
+              command_group_data.add_sub_command(name.to_sym)
+            end
+
+            # Register a group-level guard. Semantics match the per-command
+            # `guard` DSL — `:no_change` is recognized as the magic name that
+            # raises {NoChangeTransition} on failure.
+            #
+            # @param name [Symbol] the guard name
+            # @param error_extra [Hash, Proc] extra error context
+            # @yield Block returning true if the guard passes
+            # @return [void]
+            def guard(name, error_extra: {}, &)
+              command_group_data.add_guard(name)
+              guard_evaluator_class.guard(name, error_extra:, &)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/method_definers/command_group/base.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module MethodDefiners
+          module CommandGroup
+            # Base class for command_group method definers.
+            class Base
+              def initialize(command_group_data)
+                @name = command_group_data.name
+                @aggregate_class = command_group_data.aggregate_class
+              end
+
+              def call
+                raise NotImplementedError, "#{self.class} must implement #call"
+              end
+
+              private
+
+              attr_reader :name, :aggregate_class
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/method_definers/command_group/can_command_group.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module MethodDefiners
+          module CommandGroup
+            # Defines `aggregate.can_<group_name>?(payload = {})` and the
+            # `<group_name>_error` accessor on the aggregate class.
+            #
+            # Mirrors {MethodDefiners::Command::CanCommand} but resolves the
+            # group's GuardEvaluator class instead of a command's.
+            class CanCommandGroup < Base
+              def call
+                can_method = :"can_#{@name}?"
+                error_method = :"#{@name}_error"
+
+                aggregate_class.attr_accessor error_method
+                group_name = @name
+
+                aggregate_class.define_method(can_method) do |payload = {}|
+                  cmd = command_utilities.build_group_command(group_name, payload)
+                  guard_evaluator_class = command_utilities.fetch_guard_evaluator_class_for_group(group_name)
+
+                  Yes::Core::CommandHandling::GuardRunner.new(self).call(
+                    cmd, group_name, guard_evaluator_class, skip_guards: false
+                  ).present?
+                rescue Yes::Core::CommandHandling::GuardEvaluator::InvalidTransition,
+                       Yes::Core::CommandHandling::GuardEvaluator::NoChangeTransition,
+                       Yes::Core::Command::Invalid
+                  false
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/method_definers/command_group/command_group.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module MethodDefiners
+          module CommandGroup
+            # Defines `aggregate.<group_name>(payload = nil, **options)` on the
+            # aggregate class. Mirrors {MethodDefiners::Command::Command} but
+            # delegates to {Yes::Core::CommandHandling::CommandGroupHandler}.
+            class CommandGroup < Base
+              def call
+                group_name = @name
+
+                aggregate_class.define_method(group_name) do |payload = nil, **options|
+                  payload = payload.clone if payload.is_a?(Hash)
+
+                  guards = options.delete(:guards)
+                  guards = true if guards.nil?
+                  metadata = options.delete(:metadata)
+
+                  if payload.nil? && !options.empty?
+                    payload = options
+                  elsif payload.nil?
+                    payload = {}
+                  end
+
+                  Yes::Core::CommandHandling::CommandGroupHandler.new(self).call(
+                    group_name, payload, guards:, metadata:
+                  )
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate.rb

@@ -66,6 +66,7 @@ module Yes
             if tp.self == subclass
               subclass.setup_read_model_classes if subclass.read_model_enabled?
               subclass.setup_authorizer_classes
+              subclass.validate_command_groups!
               tp.disable
             end
           end.enable
@@ -76,8 +77,15 @@ module Yes
         #
         # @param name [Symbol] The name of the parent.
         # @param options [Hash] Options for configuring the parent.
+        # @option options [Boolean] :command (true) When false, skips defining the `assign_<name>` command.
+        # @option options [Array<Symbol>] :skip_default_guards ([]) Default guards (e.g. `:not_removed`)
+        #   that should not be auto-applied to the generated `assign_<name>` command. See
+        #   {.removable} for context on the `:not_removed` auto-block.
         # @yield Block for defining guards and other attribute configurations.
         # @return [void]
+        #
+        # @example Skip the auto-injected :not_removed guard on a parent's assign command
+        #   parent :tenant, skip_default_guards: %i[not_removed]
         def parent(name, **options, &)
           parent_aggregates[name] = options
 
@@ -85,7 +93,9 @@ module Yes
 
           return unless options.fetch(:command, true)
 
-          command :"assign_#{name}" do
+          skip_default_guards = options[:skip_default_guards] || []
+
+          command :"assign_#{name}", skip_default_guards: do
             payload "#{name}_id": :uuid
 
             guard(:no_change) { public_send(:"#{name}_id") != payload.public_send(:"#{name}_id") }
@@ -103,7 +113,26 @@ module Yes
 
         # Defines a default removal behavior for the aggregate.
         #
+        # In addition to defining the `:remove` command, `removable` records aggregate-level
+        # configuration that the {Yes::Core::CommandHandling::GuardEvaluator} reads at runtime
+        # to **auto-block every other command on the aggregate** while the removal attribute is
+        # set. The auto-block fires before any registered guard (including the auto-injected
+        # `:no_change`), so post-remove mutations consistently raise
+        # `GuardEvaluator::InvalidTransition` with the i18n message under
+        # `aggregates.<context>.<aggregate>.commands.<command>.guards.not_removed.error`.
+        # The `:remove` command itself is exempt and remains gated only by `:no_change`.
+        #
+        # The auto-block is order-independent: `removable` may be declared before or after the
+        # other commands on the aggregate.
+        #
+        # `attr_name` must correspond to an attribute readable on the aggregate (the macro
+        # auto-defines it as `:datetime` when missing).
+        #
         # @param attr_name [Symbol] the attribute name to use for marking removal
+        # @param not_removed_guards [Boolean] when true (default), every non-`:remove` command on
+        #   the aggregate auto-blocks while `attr_name` is set. Pass `false` to disable the
+        #   auto-block aggregate-wide; individual commands can still opt in by defining their
+        #   own `guard(:not_removed)`.
         # @yield Block for defining additional guards and other removal configurations
         # @return [void]
         #
@@ -124,16 +153,30 @@ module Yes
         #     removable(attr_name: :deleted_at)
         #   end
         #
-        def removable(attr_name: :removed_at, &)
+        # @example Disable the :not_removed auto-block aggregate-wide
+        #   class UserAggregate < Yes::Core::Aggregate
+        #     removable(not_removed_guards: false)
+        #   end
+        #
+        def removable(attr_name: :removed_at, not_removed_guards: true, &)
           attribute attr_name, :datetime unless attributes.key?(attr_name)
+          @removable_config = { attr_name:, not_removed_guards: }
 
-          command :remove do
+          command :remove, skip_default_guards: %i[not_removed] do
             guard(:no_change) { !public_send(attr_name) }
             update_state { method(attr_name).call { Time.current } }
             instance_eval(&) if block_given?
           end
         end
 
+        # Returns the removable configuration for the aggregate, or nil if {.removable} was
+        # never called.
+        #
+        # @return [Hash{Symbol => Object}, nil] hash with two keys when set:
+        #   * `:attr_name` [Symbol] — the attribute that marks removal (default `:removed_at`).
+        #   * `:not_removed_guards` [Boolean] — whether the auto-block is enabled.
+        attr_reader :removable_config
+
         # Sets the primary context for the aggregate.
         #
         # @param context [String] The primary context to set.
@@ -239,12 +282,24 @@ module Yes
         # @example Define publish command an published attribute
         #   command :publish
         #
-        def command(*args, **, &)
-          return handle_command_shortcut(*args, **, &) unless Dsl::CommandShortcutExpander.base_case?(*args, **, &)
+        # @example Skip the auto-injected :not_removed guard for a single command
+        #   command :restore, skip_default_guards: %i[not_removed] do
+        #     guard(:no_change) { removed_at.present? }
+        #     update_state { removed_at { nil } }
+        #   end
+        #
+        # All overloads accept a `skip_default_guards:` keyword argument carrying an array of
+        # default-guard symbols (currently only `:not_removed` — see {.removable}) that should
+        # not be auto-applied to the command. Defaults to `[]`.
+        #
+        def command(*args, **kwargs, &)
+          skip_default_guards = kwargs.delete(:skip_default_guards) || []
+          base_case = Dsl::CommandShortcutExpander.base_case?(*args, **kwargs, &)
+          return handle_command_shortcut(*args, skip_default_guards:, **kwargs, &) unless base_case
 
           name = args.first
           @commands ||= {}
-          command_data = Dsl::CommandData.new(name, self, { context:, aggregate: })
+          command_data = Dsl::CommandData.new(name, self, { context:, aggregate:, skip_default_guards: })
           @commands[name] = command_data
 
           Dsl::CommandDefiner.new(command_data).call(&)
@@ -283,6 +338,55 @@ module Yes
           @commands ||= {}
         end
 
+        # Defines a command_group on the aggregate.
+        #
+        # A command_group declares a compound action that runs multiple
+        # existing aggregate commands in declaration order, atomically, with
+        # the sub-commands' guards bypassed. The group itself has its own,
+        # leaner guard set declared inside the block via `guard :name`.
+        #
+        # @param name [Symbol] the group name (also the aggregate method name)
+        # @yield Block accepting `command :sub_name` and `guard :name`
+        # @return [void]
+        #
+        # @example
+        #   command_group :create_apprenticeship do
+        #     command :assign_company
+        #     command :assign_user
+        #     command :change_name
+        #     command :publish
+        #
+        #     guard(:company_assigned) { payload.company_id.present? }
+        #   end
+        def command_group(name, &)
+          @command_groups ||= {}
+          group_data = Dsl::CommandGroupData.new(name, self, context:, aggregate:)
+          @command_groups[name] = group_data
+          Dsl::CommandGroupDefiner.new(group_data).call(&)
+        end
+
+        # @return [Hash] The command groups defined on this aggregate
+        def command_groups
+          @command_groups ||= {}
+        end
+
+        # Validates that each command_group references commands actually
+        # defined on this aggregate. Called from the end-of-class
+        # {TracePoint} hook set up in {.inherited}.
+        #
+        # @raise [Dsl::CommandGroupDefiner::UnknownSubCommandError]
+        # @return [void]
+        def validate_command_groups!
+          command_groups.each do |group_name, data|
+            unknown = data.sub_command_names - commands.keys
+            next if unknown.empty?
+
+            raise Dsl::CommandGroupDefiner::UnknownSubCommandError,
+                  "command_group :#{group_name} on #{name} references unknown commands: " \
+                  "#{unknown.join(', ')}. Define them with `command :<name>` before using them."
+          end
+        end
+
         private
 
         #
@@ -295,8 +399,8 @@ module Yes
         #
         # @return [void]
         #
-        def handle_command_shortcut(...)
-          expanded = Dsl::CommandShortcutExpander.new(...).call
+        def handle_command_shortcut(*, skip_default_guards: [], **, &)
+          expanded = Dsl::CommandShortcutExpander.new(*, **, &).call
 
           expanded.attributes.each do |specification|
             next if attributes.key?(specification.name)
@@ -305,7 +409,7 @@ module Yes
           end
 
           expanded.commands.each do |specification|
-            command(specification.name, &specification.block)
+            command(specification.name, skip_default_guards:, &specification.block)
           end
         end
       end