hecks 3.4.2 → 3.6.0

data/lib/hecks/bluebook/dsl/hecksagon_builder.rb

@@ -1,4 +1,5 @@
 require_relative "word_gate"
+require_relative "hecksagon_builder/chapter_scope"
 module Hecks
   module Bluebook
     module DSL
@@ -8,35 +9,7 @@ module Hecks
         GRAMMAR_CONTEXT = "Hecksagon".freeze
 
         include WordGate
-
-        class << self
-          # The bind collector of the build running on this thread; thread-local, so a build
-          # on another thread never sees it.
-          #
-          # @return [Array, nil] the binds the running build collects into
-          def collector = Thread.current.thread_variable_get(:hecks_hecksagon_collector)
-
-          # @param value [Array, nil] the binds the running build collects into
-          def collector=(value)
-            Thread.current.thread_variable_set(:hecks_hecksagon_collector, value)
-          end
-
-          # @return [String, nil] the name of the chapter whose hecksagon is being built
-          def building = Thread.current.thread_variable_get(:hecks_hecksagon_building)
-
-          # @param value [String, nil] the name of the chapter whose hecksagon is being built
-          def building=(value)
-            Thread.current.thread_variable_set(:hecks_hecksagon_building, value)
-          end
-
-          # @return [Hash, nil] the modules this thread's build has taken off `Hecks`
-          def hidden_modules = Thread.current.thread_variable_get(:hecks_hecksagon_hidden)
-
-          # @param value [Hash, nil] the modules this thread's build has taken off `Hecks`
-          def hidden_modules=(value)
-            Thread.current.thread_variable_set(:hecks_hecksagon_hidden, value)
-          end
-        end
+        extend ChapterScope
 
         # Lets the Hecks chapter's own hecksagon spell its aggregates `Hecks::Operation`.
         #
@@ -197,77 +170,10 @@ module Hecks
           builder  = new(domain)
           resolver = ->(name) { BindingProxy.namespace(name, builder.binds) }
 
-          previous       = collector
-          previous_name  = building
-          self.collector = builder.binds
-          self.building  = domain.to_s
-          previous_hidden = hidden_modules
-          hidden = previous_name == "Hecks" ? {} : shadowed(domain)
-          self.hidden_modules = hidden.empty? ? previous_hidden : hidden
-          begin
-            ConstShim.with(resolver) { builder.instance_eval(&block) } if block
-          ensure
-            restore_shadowed(hidden)
-            self.hidden_modules = previous_hidden
-            self.collector = previous
-            self.building  = previous_name
-          end
+          scoped_to(domain, builder.binds) { ConstShim.with(resolver) { builder.instance_eval(&block) } if block }
 
           builder.build
         end
-
-        # Takes off `Hecks` each real module a chapter aggregate shares its name with, so the
-        # name reaches `ChapterConstants#const_missing`. Only the chapter named Hecks has this
-        # collision; a nested build of it leaves the outer build's shadows in place.
-        #
-        # @param domain [String, Symbol] the chapter whose hecksagon is being built
-        # @return [Hash{Symbol => Object}] what was taken off, by name: the module, or the
-        #   autoload path when the constant had not loaded yet
-        def self.shadowed(domain)
-          return {} unless domain.to_s == "Hecks"
-
-          chapter = Hecks.current_registry&.bluebook("Hecks")
-          names   = chapter ? chapter.aggregates.map { |aggregate| aggregate.hecks_name.to_sym } : []
-          names.select { |name| Hecks.const_defined?(name, false) }.to_h do |name|
-            pending = Hecks.autoload?(name)
-            held    = pending ? [:autoload, pending] : [:module, Hecks.const_get(name, false)]
-            Hecks.send(:remove_const, name)
-            [name, held]
-          end
-        end
-
-        # Runs the block with every module the running build shadowed back on `Hecks`, and a
-        # missing `Hecks::X` an ordinary `NameError`, then shadows them again. A chapter loaded
-        # from inside the hecksagon block is ordinary code, not the hecksagon's own vocabulary.
-        # A no-op when nothing is shadowed.
-        #
-        # @yield the code that must see `Hecks`'s real modules
-        # @return [Object] the block's result
-        def self.with_real_modules
-          hidden = hidden_modules
-          return yield if hidden.nil? || hidden.empty?
-
-          name = building
-          restore_shadowed(hidden)
-          self.building = nil
-          begin
-            yield
-          ensure
-            self.building = name
-            hidden.replace(shadowed(name))
-          end
-        end
-
-        # Puts back what `shadowed` took off.
-        #
-        # @param hidden [Hash{Symbol => Array}] `shadowed`'s answer
-        # @return [void]
-        def self.restore_shadowed(hidden)
-          hidden.each do |name, (kind, held)|
-            Hecks.send(:remove_const, name) if Hecks.const_defined?(name, false)
-            kind == :autoload ? Hecks.autoload(name, held) : Hecks.const_set(name, held)
-          end
-        end
       end
     end
   end

data/lib/hecks/bluebook/dsl/identity_declaration.rb

@@ -14,65 +14,15 @@ module Hecks
         # @param as [Symbol, nil] the field name to mint for a value-object-type target
         # @yield a bespoke value-object body for the identity's own value object
         # @raise [Bluebook::DSL::Malformed] on a repeat declaration or an invalid mix of forms
-        # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
         def identified_by_impl(*targets, as: nil, &definition)
           return legacy_identified_by(*targets, as: as, &definition) if MetaValidator.shadow_parsing?
 
           refuse_second_identity!
-
-          if definition
-            unless targets.empty?
-              raise Malformed,
-                    "#{@name}.identified_by cannot combine a value-object type with a block"
-            end
-
-            type_name = identity_value_object_name
-            value_object =
-              begin
-                ValueObjectBuilder.build(
-                  type_name,
-                  owner_value_objects: identity_pool,
-                  &definition
-                )
-              rescue NameError => e
-                # Must raise Malformed: EraGuard.shadow_parse retries frozen text only on
-                # Malformed, and a bare identifier in an old block form raises NameError here.
-                raise Malformed,
-                      "#{@name}.identified_by do ... end could not be read as a value-object " \
-                      "definition: #{e.message}"
-              end
-            raise Malformed, "#{@name}.identified_by do declares no identity attributes" if value_object.attributes.empty?
-
-            install_identity_value_object!(value_object)
-            @identity_type_pending = [value_object, as || :identity, attributes.size]
-            return
-          end
+          return declare_identity_block(targets, as, definition) if definition
 
           raise Malformed, "#{@name}.identified_by names no identity" if targets.empty?
 
-          if targets.one? && identity_type?(targets.first)
-            @identity_type_pending = [targets.first, as, attributes.size]
-            return
-          end
-
-          if targets.one?
-            field = targets.first
-            if as
-              raise Malformed,
-                    "#{@name}.identified_by takes no as: — name the declared field itself"
-            end
-            # Transitional: the self-hosted language and live corpus still use this form.
-            @identity_field_pending = field
-            return
-          end
-
-          unless targets.all? { |target| !identity_type?(target) }
-            raise Malformed,
-                  "#{@name}.identified_by takes one value-object type or two or more attribute names, not both"
-          end
-          raise Malformed, "#{@name}.identified_by compound keys take no as:" if as
-
-          @identity_fields_pending = targets
+          targets.one? ? declare_single_identity(targets.first, as) : declare_compound_identity(targets, as)
         end
 
         private
@@ -100,38 +50,64 @@ module Hecks
             return
           end
 
-          return unless @identity_type_pending || @identity_field_pending || @identity_fields_pending ||
-                        (@identity_paths && !@identity_paths.empty?)
+          return unless identity_declared?
 
           raise Malformed, "#{@name} declares identified_by more than once"
         end
 
-        # Parses the spellings frozen era text uses, for `EraGuard.shadow_parse`.
-        def legacy_identified_by(*targets, as:, &path)
-          target = targets.first
-          if target
-            raise Malformed, "#{@name}.identified_by takes a field name/value object or a block, not both" if path
+        def identity_declared?
+          pending = @identity_type_pending || @identity_field_pending || @identity_fields_pending
+          pending || (@identity_paths && !@identity_paths.empty?)
+        end
 
-            if targets.size > 1
-              raise Malformed, "#{@name}.identified_by takes no as: with a compound key" if as
+        def declare_identity_block(targets, as, definition)
+          raise Malformed, "#{@name}.identified_by cannot combine a value-object type with a block" unless targets.empty?
 
-              @identity_fields_pending = targets
-              return
-            end
+          value_object = build_identity_value_object(identity_value_object_name, definition)
+          raise Malformed, "#{@name}.identified_by do declares no identity attributes" if value_object.attributes.empty?
 
-            if identity_type?(target)
-              @identity_type_pending = [target, as, attributes.size]
-            else
-              if as
-                raise Malformed,
-                      "#{@name}.identified_by :#{target} takes no as: — as: only applies to identified_by ValueObject"
-              end
+          install_identity_value_object!(value_object)
+          @identity_type_pending = [value_object, as || :identity, attributes.size]
+          nil
+        end
 
-              @identity_field_pending = target
-            end
+        def build_identity_value_object(type_name, definition)
+          ValueObjectBuilder.build(type_name, owner_value_objects: identity_pool, &definition)
+        rescue NameError => e
+          # Must raise Malformed: EraGuard.shadow_parse retries frozen text only on
+          # Malformed, and a bare identifier in an old block form raises NameError here.
+          raise Malformed,
+                "#{@name}.identified_by do ... end could not be read as a value-object " \
+                "definition: #{e.message}"
+        end
+
+        def declare_single_identity(target, as)
+          if identity_type?(target)
+            @identity_type_pending = [target, as, attributes.size]
             return
           end
 
+          raise Malformed, "#{@name}.identified_by takes no as: — name the declared field itself" if as
+
+          # Transitional: the self-hosted language and live corpus still use this form.
+          @identity_field_pending = target
+          nil
+        end
+
+        def declare_compound_identity(targets, as)
+          unless targets.none? { |target| identity_type?(target) }
+            raise Malformed,
+                  "#{@name}.identified_by takes one value-object type or two or more attribute names, not both"
+          end
+          raise Malformed, "#{@name}.identified_by compound keys take no as:" if as
+
+          @identity_fields_pending = targets
+        end
+
+        # Parses the spellings frozen era text uses, for `EraGuard.shadow_parse`.
+        def legacy_identified_by(*targets, as:, &path)
+          return legacy_identity_target(targets, as, path) if targets.first
+
           raise Malformed, "#{@name}.identified_by names no field" unless path
 
           paths = Ports::Extraction.canonical(path).to_s.split.reject(&:empty?)
@@ -139,6 +115,30 @@ module Hecks
 
           @identity_paths = paths
         end
+
+        def legacy_identity_target(targets, as, path)
+          raise Malformed, "#{@name}.identified_by takes a field name/value object or a block, not both" if path
+
+          if targets.size > 1
+            raise Malformed, "#{@name}.identified_by takes no as: with a compound key" if as
+
+            @identity_fields_pending = targets
+          elsif identity_type?(targets.first)
+            @identity_type_pending = [targets.first, as, attributes.size]
+          else
+            legacy_identity_field(targets.first, as)
+          end
+          nil
+        end
+
+        def legacy_identity_field(target, as)
+          if as
+            raise Malformed,
+                  "#{@name}.identified_by :#{target} takes no as: — as: only applies to identified_by ValueObject"
+          end
+
+          @identity_field_pending = target
+        end
       end
     end
   end

data/lib/hecks/bluebook/dsl/lifecycle_builder.rb

@@ -69,9 +69,7 @@ module Hecks
           return if MetaValidator.shadow_parsing? # frozen era text is exempt
 
           @transitions.each_with_index do |(command, transition), index|
-            earlier = @transitions[0...index].find do |other_command, other|
-              other_command == command && overlap?(other, transition)
-            end
+            earlier = earlier_overlap(command, transition, index)
             next unless earlier
 
             raise Malformed,
@@ -81,6 +79,12 @@ module Hecks
           end
         end
 
+        def earlier_overlap(command, transition, index)
+          @transitions[0...index].find do |other_command, other|
+            other_command == command && overlap?(other, transition)
+          end
+        end
+
         def overlap?(one, other)
           return true if one.from.nil? || other.from.nil?
 

data/lib/hecks/bluebook/dsl/need_word.rb

@@ -23,7 +23,7 @@ module Hecks
           unless NEEDABLE_FACTS.include?(fact)
             raise Malformed,
                   "#{@name} needs :#{fact}, which the runtime cannot supply — it supplies " \
-                  "#{NEEDABLE_FACTS.map { |known| ":#{known}" }.join(', ')}"
+                  "#{NEEDABLE_FACTS.map { |known| ":#{known}" }.join(", ")}"
           end
           raise Malformed, "#{@name} declares needs :#{fact} twice" if @needs.include?(fact)
 

data/lib/hecks/bluebook/dsl/port_operation_builder.rb

@@ -60,20 +60,12 @@ module Hecks
           outbound = @direction == :outbound
           refuse_wrong_words!(outbound)
 
-          operation = PortOperation.new(
+          refuse_silent_inbound! unless outbound
+
+          PortOperation.new(
             name: @name, attributes: attributes, emits: @emits,
             direction: @direction, answers: @answers, refuses: @refuses, to: @to
           )
-
-          # Only inbound: an `asks` says it with `answers`/`refuses` instead, already enforced
-          # above.
-          if !outbound && @emits.empty?
-            raise Malformed,
-                  "#{@name} declares no emits — an operation with nothing to say " \
-                  "afterward is a call into nothing"
-          end
-
-          operation
         end
 
         private
@@ -88,25 +80,38 @@ module Hecks
         # Each direction refuses the other's words: `emits` on an `asks` names one ending and
         # leaves the other nowhere; `answers` on a `tells` promises a channel that never exists.
         def refuse_wrong_words!(outbound)
-          if outbound
-            unless @emits.empty?
-              raise Malformed, "#{@name} is an asks and declares emits — name its two endings with " \
-                               "answers and refuses instead"
-            end
-            unless @answers
-              raise Malformed, "#{@name} declares no answers — an ask with no word for what came " \
-                               "back cannot be reacted to"
-            end
-            unless @refuses
-              raise Malformed, "#{@name} declares no refuses — an ask that cannot fail is a call " \
-                               "into a system you do not control, pretending otherwise"
-            end
-          else
-            if @answers || @refuses
-              raise Malformed, "#{@name} is a tells and declares #{@answers ? 'answers' : 'refuses'} — " \
-                               "an inbound fact has no channel back to whoever sent it"
-            end
+          outbound ? refuse_outbound_gaps! : refuse_return_channel!
+        end
+
+        def refuse_outbound_gaps!
+          unless @emits.empty?
+            raise Malformed, "#{@name} is an asks and declares emits — name its two endings with " \
+                             "answers and refuses instead"
           end
+          refuse_missing_ending!(@answers, "answers", "an ask with no word for what came back cannot be reacted to")
+          refuse_missing_ending!(@refuses, "refuses",
+                                 "an ask that cannot fail is a call into a system you do not control, pretending otherwise")
+        end
+
+        def refuse_missing_ending!(ending, word, reason)
+          raise Malformed, "#{@name} declares no #{word} — #{reason}" unless ending
+        end
+
+        # Only inbound: an `asks` says it with `answers`/`refuses` instead, already enforced
+        # by `refuse_wrong_words!`.
+        def refuse_silent_inbound!
+          return unless @emits.empty?
+
+          raise Malformed,
+                "#{@name} declares no emits — an operation with nothing to say " \
+                "afterward is a call into nothing"
+        end
+
+        def refuse_return_channel!
+          return unless @answers || @refuses
+
+          raise Malformed, "#{@name} is a tells and declares #{@answers ? "answers" : "refuses"} — " \
+                           "an inbound fact has no channel back to whoever sent it"
         end
 
         # Evaluates one operation block against a fresh builder and returns what it built;

data/lib/hecks/bluebook/dsl/process_manager_builder.rb

@@ -53,15 +53,7 @@ module Hecks
         def transition_impl(mapping, &block)
           mapping = mapping.dup
           from    = mapping.delete(:from)
-
-          # `from:` is required: the saga's admission check tests `from_state` by plain equality,
-          # so a transition with no `from:` would match no instance.
-          if from.nil?
-            raise InvalidProcessManager,
-                  "#{@name}'s transition #{mapping.inspect} names no from: — a process manager's own " \
-                  "admission checks a saga instance's CURRENT state exactly, so a transition with no " \
-                  "from: would match no instance ever, silently"
-          end
+          refuse_missing_from!(mapping, from)
 
           handler = HandlerBuilder.new
           handler.instance_eval(&block) if block
@@ -110,6 +102,17 @@ module Hecks
 
         private
 
+        # `from:` is required: the saga's admission check tests `from_state` by plain equality,
+        # so a transition with no `from:` would match no instance.
+        def refuse_missing_from!(mapping, from)
+          return unless from.nil?
+
+          raise InvalidProcessManager,
+                "#{@name}'s transition #{mapping.inspect} names no from: — a process manager's own " \
+                "admission checks a saga instance's CURRENT state exactly, so a transition with no " \
+                "from: would match no instance ever, silently"
+        end
+
         # One row per source state, since a `ProcessManagerHandler` carries a single `from_state`.
         def expand(event_type, transition, dispatches)
           sources = transition.from.nil? ? [nil] : Array(transition.from)
@@ -130,18 +133,7 @@ module Hecks
         end
 
         def validate!
-          unless @correlates_by
-            raise InvalidProcessManager, "#{@name} declares no correlates_by — " \
-                                         "nothing would tie its events to one instance"
-          end
-
-          # Names a scalar (`:"end_to_end.value"`), never a whole field or value object.
-          # A syntactic check: the dotted spelling leaves no question about the key's type.
-          unless @correlates_by.to_s.include?(".")
-            raise InvalidProcessManager, "#{@name} correlates_by #{@correlates_by.inspect}, which names a whole " \
-                                         "field rather than one of its scalars — say which one, e.g. " \
-                                         "#{@correlates_by}.value"
-          end
+          refuse_bad_correlation!
 
           if @starts_on.to_s.empty?
             raise InvalidProcessManager, "#{@name} declares no starts_on — " \
@@ -156,6 +148,21 @@ module Hecks
           refuse_ambiguous_legs!
         end
 
+        def refuse_bad_correlation!
+          unless @correlates_by
+            raise InvalidProcessManager, "#{@name} declares no correlates_by — " \
+                                         "nothing would tie its events to one instance"
+          end
+
+          # Names a scalar (`:"end_to_end.value"`), never a whole field or value object.
+          # A syntactic check: the dotted spelling leaves no question about the key's type.
+          return if @correlates_by.to_s.include?(".")
+
+          raise InvalidProcessManager, "#{@name} correlates_by #{@correlates_by.inspect}, which names a whole " \
+                                       "field rather than one of its scalars — say which one, e.g. " \
+                                       "#{@correlates_by}.value"
+        end
+
         # A leg is selected by (event, current state), so two legs on the same pair would
         # be picked by declaration order; `from: [...]` fan-out counts.
         def refuse_ambiguous_legs!
@@ -164,17 +171,19 @@ module Hecks
           seen = {}
           @handlers.each do |handler|
             key = [handler.event_type, handler.from_state]
-            if (earlier = seen[key])
-              raise InvalidProcessManager,
-                    "#{@name} declares two transitions on #{handler.event_type.inspect} from " \
-                    "#{handler.from_state.inspect} (=> #{earlier.to_state.inspect} and => " \
-                    "#{handler.to_state.inspect}) — a leg is selected by (event, current state), so " \
-                    "only one may answer"
-            end
+            refuse_ambiguous_pair!(handler, seen[key]) if seen[key]
             seen[key] = handler
           end
         end
 
+        def refuse_ambiguous_pair!(handler, earlier)
+          raise InvalidProcessManager,
+                "#{@name} declares two transitions on #{handler.event_type.inspect} from " \
+                "#{handler.from_state.inspect} (=> #{earlier.to_state.inspect} and => " \
+                "#{handler.to_state.inspect}) — a leg is selected by (event, current state), so " \
+                "only one may answer"
+        end
+
         # The body of one `transition ... do ... end` block; collects its `dispatch` calls.
         class HandlerBuilder
           GRAMMAR_CONTEXT = "Handler".freeze
@@ -199,30 +208,37 @@ module Hecks
           # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if `command_ref`
           #   is quoted text outside shadow-parsing
           def dispatch_impl(command_ref, with: nil, &block)
-            if command_ref.is_a?(::String) && !MetaValidator.shadow_parsing?
-              raise InvalidProcessManager,
-                    "dispatch #{command_ref.inspect} is quoted text — give the bare command constant " \
-                    "instead, e.g. dispatch Account::Debit"
-            end
+            refuse_quoted_command!(command_ref)
 
             spec = DispatchSpec.new(
               command_name: Naming.command_ref(command_ref),
               with_spec:    (with || {}).to_a
             )
             spec.instance_variable_set(:@projection_declared, !with.nil?)
-
-            if block
-              builder = DispatchBuilder.new
-              builder.instance_eval(&block)
-              # `instance_variable_get`, not a public reader: a reader would be a method the
-              # grammar never declares (syntax_conformance_spec).
-              spec.compensates = builder.instance_variable_get(:@compensates_spec)
-            end
+            spec.compensates = compensation_from(block) if block
 
             @dispatches << spec
             spec
           end
 
+          private
+
+          def refuse_quoted_command!(command_ref)
+            return unless command_ref.is_a?(::String) && !MetaValidator.shadow_parsing?
+
+            raise InvalidProcessManager,
+                  "dispatch #{command_ref.inspect} is quoted text — give the bare command constant " \
+                  "instead, e.g. dispatch Account::Debit"
+          end
+
+          # `instance_variable_get`, not a public reader: a reader would be a method the
+          # grammar never declares (syntax_conformance_spec).
+          def compensation_from(block)
+            builder = DispatchBuilder.new
+            builder.instance_eval(&block)
+            builder.instance_variable_get(:@compensates_spec)
+          end
+
           # The nested scope `dispatch ... do ... end` opens; its one word, `compensates`,
           # takes the same arguments as `dispatch` and resolves in the same saga scope.
           class DispatchBuilder

data/lib/hecks/bluebook/dsl/query_builder.rb

@@ -79,21 +79,7 @@ module Hecks
         def build
           seal_cursor
           refuse_undeclared_needs!
-          Query.new(
-            name:           @name,
-            description:    @description,
-            attributes:     attributes,
-            wheres:         @wheres,
-            order_by:       @order_by,
-            limit:          @limit,
-            offset:         @offset,
-            cursor:         @cursor,
-            authorization:  @authorization,
-            null_semantics: @null_semantics,
-            inspection:     @inspection,
-            returns:        @returns,
-            needs:          @needs
-          )
+          Query.new(**query_shape, **query_policy, returns: @returns, needs: @needs)
         end
 
         # Evaluates a `query` block against a fresh builder, then fills in owner-derived types.
@@ -116,6 +102,17 @@ module Hecks
 
         private
 
+        # The query's name, parameters and filtering clauses.
+        def query_shape
+          { name: @name, description: @description, attributes: attributes, wheres: @wheres,
+            order_by: @order_by, limit: @limit, offset: @offset, cursor: @cursor }
+        end
+
+        # How the query is authorised and how it treats nulls.
+        def query_policy
+          { authorization: @authorization, null_semantics: @null_semantics, inspection: @inspection }
+        end
+
         # Fills in a block parameter that names an owner attribute (`query "X" do |decision|`)
         # with the owner's type, unless the body declared it. Unmatched names are left for
         # MetaValidator's unresolved-attribute check.