hecks 3.4.2 → 3.6.0

data/lib/hecks/bluebook/meta_validator/judge/dispatching.rb

@@ -0,0 +1,111 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      class Judge
+        # Offering one declaration to the meta-domain: the dispatch itself, and the payloads of the
+        # creating command, the setters, the list appenders and the sealers.
+        module Dispatching
+          private
+
+          def args(pairs) = pairs.compact
+
+          def offer(label)
+            yield
+          rescue Runtime::GivenNotMet, Runtime::InvariantViolation,
+                 Runtime::TypeMismatch, Runtime::NotFound => e
+            # NotFound is a verdict, not noise: an attribute's type is a
+            # reference to its value object, so "no ValueObject with id ..."
+            # is `attributes must use value-object types` refusing.
+            @refusals << "#{label}: #{e.message}"
+          rescue Runtime::UnknownVerb
+            nil
+          end
+
+          # Wrapped in judge_bootstrapping: the walk's own values sometimes
+          # arrive as raw types a real domain command would never accept,
+          # and only a judge's own dispatch should relax for that.
+          def send_to(verb, label, to: nil, **payload)
+            Runtime::Value.judge_bootstrapping do
+              offer(label) { @runtime.dispatch(verb, to: to, with: args(payload)) }
+            end
+          end
+
+          def declare(plan, visit, id, extra = {})
+            return unless plan.declare
+
+            payload = declared_payload(plan, visit)
+            send_to("Bluebook::#{verb_for(plan, plan.declare)}", id, to: id, **payload.merge(extra))
+          end
+
+          def declared_payload(plan, visit)
+            payload = parent_link(plan, visit)
+            plan.fields.each { |field| payload[field.to_sym] = declared_field(plan, visit, field) }
+            payload
+          end
+
+          def parent_link(plan, visit)
+            return {} unless plan.parent_key
+
+            { plan.parent_key.to_sym => carried(plan, plan.declare, plan.parent_key, visit.parent_id) }
+          end
+
+          def declared_field(plan, visit, field)
+            return v(visit.index) if field == POSITION
+
+            carried(plan, plan.declare, field, field_value(visit.category, visit.node, field.to_sym, visit.parent_id))
+          end
+
+          # A setter whose every source is absent is not dispatched —
+          # offering "" would make a rule refuse a bluebook that is
+          # well-formed.
+          def setters(plan, visit, receiver)
+            plan.setters.each do |setter|
+              payload = setter.targets.to_h do |target, argument|
+                [argument.to_sym, v(setter_value(visit.category, visit.node, target))]
+              end
+              next if payload.values.all?(&:nil?)
+
+              send_to("Bluebook::#{verb_for(plan, setter.verb)}", receiver[:aggregate], to: address(receiver), **payload)
+            end
+          end
+
+          def appends(plan, visit, receiver)
+            id = receiver[:entities].last || receiver[:aggregate]
+            owner_id = owning_aggregate_ref(visit.category, id, visit.parent_id)
+            plan.appends.each do |list_name, append|
+              rows_for(visit.category, list_name, visit.node).each_with_index do |row, index|
+                offer_append(plan, visit, receiver, Appending.new(list_name, append, row, index, id, owner_id))
+              end
+            end
+          end
+
+          def offer_append(plan, visit, receiver, item)
+            chosen = append_for(visit.category, item.list_name, item.append, item.row, visit.node)
+
+            send_to("Bluebook::#{verb_for(plan, chosen.verb)}", "#{item.id}##{item.list_name}[#{item.index}]",
+                    to: address(receiver), **append_payload(visit, item, chosen))
+          end
+
+          def append_payload(visit, item, chosen)
+            chosen.map.to_h do |field, argument|
+              [argument.to_sym, appended_value(visit, item, chosen, field, argument)]
+            end
+          end
+
+          # `position` is the walk index, as in `declare`: an appended
+          # element is ordered by where the walk found it.
+          def appended_value(visit, item, chosen, field, argument)
+            return v(item.index) if field.to_s == POSITION
+
+            carried(@plan.category(visit.category), chosen.verb, argument, cell(visit.category, item, chosen, field))
+          end
+
+          def sealers(plan, receiver)
+            id = receiver[:entities].last || receiver[:aggregate]
+            plan.sealers.each { |verb| send_to("Bluebook::#{verb_for(plan, verb)}", id, to: address(receiver)) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/meta_validator/judge/identity.rb

@@ -0,0 +1,108 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      class Judge
+        # How the judge names and addresses what it offers: record ids, dotted verb paths, and
+        # the wrapping of a value as the one-field value object the language expects.
+        module Identity
+          private
+
+          # nil stays nil so an optional field reads as undeclared rather
+          # than declared-empty; an Integer passes through raw so a typed
+          # field (RowCount's `value`) still hits its own type gate.
+          def v(text)
+            return nil if text.nil?
+            return { value: text } if text.is_a?(Integer)
+
+            { value: text.to_s }
+          end
+
+          # A reference argument is passed as the bare id it names; every
+          # other field is wrapped as a one-field value object instead.
+          def carried(plan, verb, argument, value)
+            return v(value) unless plan && verb && plan.references?(verb, argument)
+
+            value
+          end
+
+          # A record's id is its declared identity, joined the same way the
+          # runtime joins it, so there is exactly one way to name a thing.
+          # Each part comes from the parent link, the walk index
+          # (`position`), or a field read off the node.
+          def identify(visit)
+            plan = @plan.category(visit.category)
+            return declared_name(visit.node) unless plan
+
+            Naming.identity(plan.identity_paths.map { |path| identity_part(plan, path, visit) })
+          end
+
+          def identity_part(plan, path, visit)
+            head = path.to_s.split(".").first
+            return visit.parent_id.to_s if head == plan.parent_key.to_s || head == OWNER
+            return visit.index.to_s     if head == POSITION
+
+            v_scalar(field_value(visit.category, visit.node, head.to_sym, visit.parent_id))
+          end
+
+          # The scalar inside whatever the reading handed back: a name is
+          # already one, a value object is not.
+          def v_scalar(held)
+            return held.to_s unless held.respond_to?(:to_h) && !held.is_a?(String)
+
+            held.to_h.values.first.to_s
+          end
+
+          # Each identity field comes from one of three places: the parent
+          # link, the walk's own index (`POSITION`), or a real field read off
+          # the node.
+          def node_identity(plan, visit)
+            plan.identity_paths.each_with_object({}) do |path, fields|
+              head = path.to_s.split(".").first
+              next if head == OWNER
+
+              fields[head.to_sym] = identity_field(plan, head, visit)
+            end
+          end
+
+          def identity_field(plan, head, visit)
+            return v(visit.index) if head == POSITION
+
+            carried(plan, plan.declare, head, identity_source(plan, head, visit))
+          end
+
+          # The raw value an identity head reads from: the parent link, or a field of the node.
+          def identity_source(plan, head, visit)
+            return visit.parent_id if head == plan.parent_key.to_s
+
+            field_value(visit.category, visit.node, head.to_sym, visit.parent_id)
+          end
+
+          # An ordinary category's own top-level aggregate reaches every
+          # verb bare; an entity-owned one prefixes its parent's own dotted
+          # path instead (ADR 0026), since a nested entity's parent may
+          # itself be entity-owned.
+          def dotted_prefix(plan)
+            return plan.name unless plan.entity_owned
+
+            "#{dotted_prefix(@plan.category(plan.parent))}.#{plan.name}"
+          end
+
+          # Entity-owned categories have no top-level aggregate to route a
+          # bare verb into, so the verb is addressed by this category's
+          # full dotted path instead.
+          def verb_for(plan, verb)
+            "#{dotted_prefix(plan)}.#{verb}"
+          end
+
+          # A bare id when there is no entity hop (the common case); the
+          # full {aggregate:, entities:} envelope only when there is one.
+          def address(receiver)
+            return receiver[:aggregate] if receiver[:entities].empty?
+
+            receiver
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/meta_validator/judge/walking.rb

@@ -0,0 +1,141 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      class Judge
+        # The walk over a built bluebook: every sibling is declared before any is detailed, and
+        # each node's own setters, appends, children and sealers are offered in a fixed order.
+        module Walking
+          private
+
+          # Every sibling is declared before any is detailed, so one
+          # sibling's attribute can reference another declared later in
+          # the same file.
+          def declare_node(visit, extra = {})
+            plan = @plan.category(visit.category)
+            return unless plan
+
+            declare(plan, visit, identify(visit), extra)
+          end
+
+          def detail_node(visit, extra = {}, receiver: nil)
+            plan = @plan.category(visit.category)
+            return unless plan
+
+            id = identify(visit)
+            # `extra` carries every entity-owned ancestor's identity down to
+            # this node; an ordinary category ignores it and locates its
+            # record through `id:` instead, so merging it in would be
+            # refused as an unrecognized argument.
+            identity = extra.merge(node_identity(plan, visit))
+
+            detail_in_order(plan, visit, id, identity, receiver || { aggregate: id, entities: [] })
+          end
+
+          # A node's own parts, in the order the language needs them offered.
+          def detail_in_order(plan, visit, id, identity, receiver)
+            eager, later = children_split(visit.category)
+
+            walk_children(eager, visit, id, identity, receiver)
+            setters(plan, visit, receiver)
+            # Before `appends`: a nested entity referenced from this node's
+            # own attribute list must exist before that list is walked.
+            nest_entities(visit, id)
+            appends(plan, visit, receiver)
+            walk_children(later, visit, id, identity, receiver)
+            within_entity(visit, id)
+            sealers(plan, receiver)
+          end
+
+          # `children_of`'s order is incidental (plan registration order);
+          # the eager ones keep only what EAGER_CHILDREN promises, in the order it does.
+          def children_split(category)
+            eager, later = children_of(category).partition { |child| eager?(category, child) }
+            [Array(EAGER_CHILDREN[category]) & eager, later]
+          end
+
+          def walk_children(children, visit, id, identity, receiver)
+            children.each do |child|
+              walk_all(child, visit.node, id, entity_child_extra(child, identity), receiver: receiver)
+            end
+          end
+
+          # Only an entity-owned child needs the accumulated ancestor
+          # identity; an ordinary child dispatches through its own
+          # top-level aggregate.
+          def entity_child_extra(child, identity)
+            @plan.category(child)&.entity_owned ? identity : {}
+          end
+
+          def walk_all(category, node, parent_id, extra = {}, receiver: nil)
+            reader = collection_reader(category)
+            return unless node.respond_to?(reader)
+
+            visits = Array(node.public_send(reader)).each_with_index.map do |child, index|
+              Visit.new(category, child, parent_id, index)
+            end
+            declare_all(visits, extra)
+            detail_all(visits, extra, receiver)
+          end
+
+          def declare_all(visits, extra)
+            visits.each { |visit| declare_node(visit, extra) }
+          end
+
+          def detail_all(visits, extra, receiver)
+            visits.each { |visit| detail_node(visit, extra, receiver: child_receiver(visit, receiver)) }
+          end
+
+          # An entity-owned child is addressed by its root aggregate and the chain of entities
+          # leading to it; any other child needs no receiver of its own.
+          def child_receiver(visit, receiver)
+            return unless @plan.category(visit.category)&.entity_owned
+
+            root = receiver || { aggregate: visit.parent_id, entities: [] }
+            { aggregate: root[:aggregate], entities: Array(root[:entities]) + [identify(visit)] }
+          end
+
+          # Addressed under the piece so a command name can't collide
+          # between an aggregate and one of its entities; `aggregate` says
+          # what a reference resolves against, `entity_id` says which
+          # piece declared it.
+          def within_entity(visit, id)
+            return unless visit.category == "Entity"
+
+            WITHIN_ENTITY.each do |child|
+              plan = @plan.category(child)
+              walk_all(child, visit.node, id, {
+                         aggregate: carried(plan, plan&.declare, "aggregate", visit.parent_id),
+                         entity_id: carried(plan, plan&.declare, "entity_id", id)
+                       })
+            end
+          end
+
+          # An entity may nest further entities (ADR 0026): `aggregate`
+          # stays the walk's root, while `owner` is this entity's own
+          # direct parent — what tells a nested entity apart from a
+          # root-level one sharing that same root.
+          def nest_entities(visit, id)
+            return unless visit.category == "Entity"
+
+            plan = @plan.category("Entity")
+            walk_all("Entity", visit.node, visit.parent_id, {
+                       aggregate: carried(plan, plan&.declare, "aggregate", visit.parent_id),
+                       owner:     carried(plan, plan&.declare, "owner", id)
+                     })
+          end
+
+          def children_of(category)
+            @plan.names.select { |name| @plan.category(name).parent == category }
+          end
+
+          def eager?(category, child) = Array(EAGER_CHILDREN[category]).include?(child)
+
+          # Command -> commands, ValueObject -> value_objects, Query ->
+          # queries: convention, not a table. Naming.plural is kept as the
+          # single implementation, so a second one can't disagree with it.
+          def collection_reader(category) = Naming.plural(Naming.snake(category))
+        end
+      end
+    end
+  end
+end