hecks 3.5.0 → 3.7.0

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/hop_tails.rb

@@ -0,0 +1,79 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        module Validation
+          # One hopped `where`: the aggregate and query that ask, the clause, and the aggregate
+          # the hop lands on.
+          HopSite = Struct.new(:aggregate, :query, :clause, :target) do
+            # @return [String] how a refusal names the asking query: `Aggregate.Query`
+            def label = "#{aggregate.hecks_name}.#{query.hecks_name}"
+          end
+          private_constant :HopSite
+
+          # Checks where a hop lands: the field the clause asks about on the aggregate it hops to,
+          # and the comparator it is compared with.
+          module HopTails
+            private
+
+            # Same three-way answer as `seal_query_field` (scalar, value object, or
+            # nothing), asked of the hop's target.
+            def validate_hop_tail!(site, tail)
+              name, *nested = tail.to_s.split(".")
+              attribute = site.target.attributes.find { |candidate| candidate.name.to_s == name }
+              return validate_hop_comparator!(site, attribute, nested) if hop_tail_scalar?(site.target, attribute, name, nested)
+
+              refuse_hop_tail!(site, attribute, tail, nested)
+            end
+
+            def hop_tail_scalar?(target, attribute, name, nested)
+              return attribute || target.lifecycle&.field.to_s == name if nested.empty?
+
+              attribute && QuerySpecification::FieldPath.scalar_leaf?(attribute, nested) { |type| target.value_object(type) }
+            end
+
+            def refuse_hop_tail!(site, attribute, tail, nested)
+              target = site.target
+              asks = "#{site.label} asks about #{site.clause.field}, which hops to #{target.hecks_name} " \
+                     "and then asks about #{tail}, which"
+              raise Malformed, "#{asks} #{hop_tail_fault(target, attribute, nested)}"
+            end
+
+            def hop_tail_fault(target, attribute, nested)
+              if nested.any? && attribute && hop_leaf_resolves?(target, attribute, nested)
+                "lands on a value object, not a scalar — a dotted query path ends on a " \
+                  "scalar member, or the engines answer it differently"
+              else
+                "#{target.hecks_name} never declares — a query over a field that does " \
+                  "not exist matches nothing and refuses nothing"
+              end
+            end
+
+            def hop_leaf_resolves?(target, attribute, nested)
+              !QuerySpecification::FieldPath.leaf_attribute(attribute, nested) { |type| target.value_object(type) }.nil?
+            end
+
+            # An ordered comparator over a hopped field must land on a number; the check
+            # `AggregateBuilder#seal_ordered_comparator` deferred.
+            def validate_hop_comparator!(site, attribute, nested)
+              clause = site.clause
+              return unless AggregateBuilder::ORDERED_COMPARATORS.include?(clause.op.to_s.to_sym)
+              return if attribute && numeric_hop_leaf?(site.target, attribute, nested)
+
+              held = attribute ? "holds no number" : "is the lifecycle field, which holds text"
+              raise Malformed,
+                    "#{site.label} compares #{clause.field} with " \
+                    "#{clause.op} after hopping to #{site.target.hecks_name}, but the field it lands " \
+                    "on #{held} — an ordered comparison needs a numeric field, and over " \
+                    "anything else the adapters answer differently or not at all"
+            end
+
+            def numeric_hop_leaf?(target, attribute, nested)
+              QuerySpecification::FieldPath.numeric?(attribute, nested) { |type| target.value_object(type) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/projected_fields.rb

@@ -0,0 +1,76 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        module Validation
+          # Checks that each `projects` reference resolves to an aggregate declaring the remote
+          # field as a scalar, once every aggregate in the chapter exists.
+          module ProjectedFields
+            private
+
+            # Checks each `projects` reference resolves to an aggregate declaring
+            # `remote_field` as a scalar. A single hop never reaches HopPath::MAX_HOPS, so
+            # :too_deep is not special-cased.
+            def validate_projected_fields!(bluebook)
+              bluebook.aggregates.each do |aggregate|
+                aggregate.projected_fields.each { |field| validate_projected_field!(aggregate, field) }
+              end
+            end
+
+            # Checks that one `projects` field's reference resolves to a real scalar.
+            def validate_projected_field!(aggregate, field)
+              plan = projection_plan(aggregate, field)
+              refuse_unresolvable_projection!(aggregate, field, plan) if plan.refusal == :unresolvable
+              validate_projection_target!(aggregate, field, plan)
+            end
+
+            def validate_projection_target!(aggregate, field, plan)
+              target = plan.hops.last.target
+              remote_attribute = target.attributes.find { |candidate| candidate.name.to_s == plan.tail }
+              return if remote_attribute.nil? && implicit_projection_target?(target, plan.tail)
+
+              refuse_undeclared_projection!(aggregate, field, target, plan) unless remote_attribute
+              refuse_non_scalar_projection!(aggregate, field, target, plan) unless projectable_scalar?(target, remote_attribute)
+            end
+
+            def projection_plan(aggregate, field)
+              QuerySpecification::HopPath.plan("#{field.reference}/#{field.remote_field}", aggregate.attributes)
+            end
+
+            # A lifecycle field is a plain string by construction, so a name match is enough (as in
+            # `validate_hop_tail!`). A projection may chain through another projection;
+            # `projected_fields` is separate from `attributes`, and a projected value is always a
+            # scalar by construction, so a name match is enough there too.
+            def implicit_projection_target?(target, tail)
+              target.lifecycle&.field.to_s == tail || target.projected_fields.any? { |f| f.name.to_s == tail }
+            end
+
+            def refuse_unresolvable_projection!(aggregate, field, plan)
+              raise Malformed,
+                    "#{aggregate.hecks_name}.projects :#{field.name} reads through :#{field.reference}, " \
+                    "which hops to #{plan.hops.last.target_name}, which this chapter never declares — " \
+                    "a projection through an aggregate this chapter cannot see resolves to nothing"
+            end
+
+            def refuse_undeclared_projection!(aggregate, field, target, plan)
+              raise Malformed,
+                    "#{aggregate.hecks_name}.projects :#{field.name} reads #{target.hecks_name}'s own " \
+                    "#{plan.tail.inspect}, which #{target.hecks_name} never declares"
+            end
+
+            def refuse_non_scalar_projection!(aggregate, field, target, plan)
+              raise Malformed,
+                    "#{aggregate.hecks_name}.projects :#{field.name} reads #{target.hecks_name}'s own " \
+                    "#{plan.tail.inspect}, which is not a scalar — a projected field copies a single " \
+                    "value, never a reference, a value object, or a list"
+            end
+
+            def projectable_scalar?(target, attribute)
+              !attribute.list? && !attribute.reference? && target.value_object(attribute.type).nil?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/provisions.rb

@@ -0,0 +1,65 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        module Validation
+          # Checks every `provides` row of a chapter against `Capabilities::CONTRACTS`.
+          module Provisions
+            private
+
+            # Checks every `provides` row against `Capabilities::CONTRACTS`.
+            def validate_provisions!(bluebook)
+              bluebook.provides.group_by(&:capability).each do |capability, rows|
+                validate_provision!(bluebook, capability, rows)
+              end
+            end
+
+            def validate_provision!(bluebook, capability, rows)
+              contract = Capabilities::CONTRACTS.fetch(capability) do
+                raise Malformed, "#{bluebook.name} provides #{capability.inspect}, which is no capability the " \
+                                 "language knows — known: #{Capabilities::CONTRACTS.keys.sort.join(", ")}"
+              end
+
+              refuse_wrong_provision_keys!(bluebook, capability, rows, contract)
+              rows.each { |row| validate_provided_verb!(bluebook, capability, row, contract.fetch(row.key.to_sym)) }
+            end
+
+            def refuse_wrong_provision_keys!(bluebook, capability, rows, contract)
+              keys = rows.map { |row| row.key.to_sym }
+              return if keys.sort == contract.keys.sort
+
+              raise Malformed, "#{bluebook.name} provides #{capability.inspect} with #{keys.join(", ")}, but " \
+                               "#{capability} needs exactly #{contract.keys.join(", ")}"
+            end
+
+            def validate_provided_verb!(bluebook, capability, row, kind)
+              return validate_provided_port_operation!(bluebook, capability, row) if kind == :port_operation
+
+              aggregate_name, member = row.verb.split(".", 2)
+              aggregate = bluebook.aggregate(aggregate_name)
+              return if aggregate && member && provided_member_names(aggregate, kind).include?(member)
+
+              raise Malformed, "#{bluebook.name} provides #{capability.inspect} #{row.key}: #{row.verb.inspect}, " \
+                               "which names no #{kind} this chapter declares (spelled \"Aggregate.#{kind.capitalize}\")"
+            end
+
+            # Only the verb's shape and aggregate are checkable here: the port is declared
+            # in the hecksagon, which attaches after the chapter is built. `Registry#verify!`
+            # checks the operation.
+            def validate_provided_port_operation!(bluebook, capability, row)
+              aggregate_name, port, operation = row.verb.split(".", 3)
+              return if bluebook.aggregate(aggregate_name) && port && operation && !operation.include?(".")
+
+              raise Malformed, "#{bluebook.name} provides #{capability.inspect} #{row.key}: #{row.verb.inspect}, " \
+                               "which is not spelled \"Aggregate.Port.Operation\" over an aggregate this chapter declares"
+            end
+
+            def provided_member_names(aggregate, kind)
+              kind == :command ? aggregate.commands.map(&:hecks_name) : aggregate.queries.map(&:name)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/query_hops.rb

@@ -0,0 +1,123 @@
+require_relative "hop_tails"
+
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        module Validation
+          # Resolves and checks the `where` hops that `AggregateBuilder` could only recognise at
+          # seal time: a hop needs the other aggregates, which exist once the chapter is assembled.
+          module QueryHops
+            include HopTails
+
+            private
+
+            # Resolves and checks every `where` hop deferred at aggregate-seal time.
+            # An entity query that hops through a reference is refused outright: nothing follows
+            # the hop at runtime (`QueryInterpreter#entity_rows` reads fields by literal key),
+            # so it would match nothing.
+            def validate_query_hops!(bluebook)
+              bluebook.aggregates.each do |aggregate|
+                aggregate.queries.each do |query|
+                  query.wheres.each do |clause|
+                    validate_hop_clause!(aggregate, query, clause) if hop_clause?(aggregate, clause)
+                  end
+                end
+
+                aggregate.entities.each { |entity| refuse_entity_query_hops!(aggregate, entity) }
+              end
+            end
+
+            def hop_clause?(aggregate, clause)
+              QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes)
+            end
+
+            # Mints an implicit query attribute for each symbolic hop comparison, typed from
+            # the scalar it compares against.
+            def infer_hop_query_arguments!(bluebook)
+              bluebook.aggregates.each do |aggregate|
+                aggregate.queries.each do |query|
+                  query.wheres.each do |clause|
+                    leaf = inferred_hop_argument(aggregate, query, clause)
+                    query.attributes << leaf if leaf
+                  end
+                end
+              end
+            end
+
+            def inferred_hop_argument(aggregate, query, clause)
+              name = clause.value
+              return unless name.is_a?(Symbol) && !query.attribute(name) && hop_clause?(aggregate, clause)
+
+              plan = QuerySpecification::HopPath.plan(clause.field, aggregate.attributes)
+              return if plan.refusal || plan.hops.empty?
+
+              inferred_hop_leaf(name, plan)
+            end
+
+            def inferred_hop_leaf(name, plan)
+              target = plan.hops.last.target
+              head, *nested = plan.tail.to_s.split(".")
+              return Attribute.new(name: name, type: String) if nested.empty? && target.lifecycle&.field.to_s == head
+
+              found = hop_leaf(target, head, nested)
+              found && Attribute.new(name: name, type: found.type, list: found.list?)
+            end
+
+            def hop_leaf(target, head, nested)
+              root = target.attributes.find { |candidate| candidate.name.to_s == head }
+              root && QuerySpecification::FieldPath.leaf_attribute(root, nested) { |type| target.value_object(type) }
+            end
+
+            def refuse_entity_query_hops!(aggregate, entity)
+              entity.queries.each do |query|
+                query.wheres.each do |clause|
+                  next unless QuerySpecification::HopPath.hop_head?(clause.field, entity.attributes)
+
+                  raise Malformed,
+                        "#{aggregate.hecks_name}::#{entity.hecks_name}.#{query.hecks_name} asks about " \
+                        "#{clause.field}, which hops through #{entity.hecks_name}'s own reference — " \
+                        "an entity query does not follow a hop the way an aggregate's own does; ask " \
+                        "through the aggregate's own query instead, or open the target directly"
+                end
+              end
+            end
+
+            def validate_hop_clause!(aggregate, query, clause)
+              plan = QuerySpecification::HopPath.plan(clause.field, aggregate.attributes)
+              refuse_hop_plan!(HopSite.new(aggregate, query, clause, nil), plan)
+
+              site = HopSite.new(aggregate, query, clause, plan.hops.last.target)
+              validate_hop_tail!(site, plan.tail)
+            end
+
+            def refuse_hop_plan!(site, plan)
+              asks = "#{site.label} asks about #{site.clause.field}"
+              case plan.refusal
+              when :unresolvable then refuse_unresolvable_hop!(asks, plan)
+              when :too_deep     then refuse_too_deep_hop!(asks)
+              end
+            end
+
+            # HopPath.plan pushes even an unresolved hop onto `hops`, so `target_name`
+            # is always there.
+            def refuse_unresolvable_hop!(asks, plan)
+              raise Malformed,
+                    "#{asks}, which hops to #{plan.hops.last.target_name}, which this chapter never " \
+                    "declares — a hop into an aggregate this chapter cannot see resolves to " \
+                    "nothing, and a where that resolves to nothing matches nothing and " \
+                    "refuses nothing"
+            end
+
+            def refuse_too_deep_hop!(asks)
+              raise Malformed,
+                    "#{asks}, whose hop chain reaches #{QuerySpecification::HopPath::MAX_HOPS} " \
+                    "references deep without landing — a chain this long is refused as a " \
+                    "likely mistake, not a structural limit"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/references.rb

@@ -0,0 +1,112 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        module Validation
+          # Checks of how a chapter's aggregates point at each other: the chapter's own namespace,
+          # entity commands that root on themselves, and reference rings.
+          module References
+            private
+
+            # A chapter's constants install under its name, or its `namespace`; landing in the
+            # gem's own `Hecks` module would shadow the gem's modules (ADR 0080), so it refuses.
+            def validate_not_the_gem_module!(bluebook)
+              return unless (bluebook.namespace || bluebook.name) == "Hecks"
+
+              raise Malformed, "#{bluebook.name}'s constants would install in the gem's own Hecks module — " \
+                               "declare a namespace, such as namespace \"Hecks::Domain\", or rename the chapter"
+            end
+
+            # Refuses an entity command that names its own entity as its root.
+            # `CommandBuilder#reference_to` sets `references` only to the owner's bare name, so on
+            # an aggregate command a head lookup is a tautology; only an entity self-reference
+            # fails.
+            def validate_reference_value_objects!(aggregates)
+              heads = aggregates.map(&:hecks_name)
+              violations = aggregates.flat_map { |aggregate| entity_root_violations(aggregate, heads) }
+              return if violations.empty?
+
+              raise Malformed,
+                    "an entity command is addressed through its aggregate; #{violations.uniq.join("; ")}"
+            end
+
+            def entity_root_violations(aggregate, heads)
+              aggregate.entities.flat_map do |entity|
+                entity.commands.filter_map do |command|
+                  next unless command.references && !heads.include?(command.references.to_s)
+
+                  "#{aggregate.hecks_name}.#{entity.hecks_name}.#{command.hecks_name} names itself as its root"
+                end
+              end
+            end
+
+            # A reference ring means no aggregate in it is a consistency boundary. Checked at
+            # chapter level because seeing a cycle needs every end declared (ADR 0025). Catches
+            # any ring length; self-reference stays legal, and a cross-chapter target is a
+            # dangling name, not an edge.
+            def validate_no_bidirectional_references!(aggregates)
+              cycle = find_reference_cycle(reference_edges(aggregates))
+              return unless cycle
+
+              raise Malformed, reference_cycle_message(cycle)
+            end
+
+            def reference_edges(aggregates)
+              aggregates.to_h do |aggregate|
+                [aggregate.hecks_name, aggregate.reference_targets.uniq.reject { |target| target == aggregate.hecks_name }]
+              end
+            end
+
+            def reference_cycle_message(cycle)
+              ring = "#{cycle.join(" -> ")} -> #{cycle.first}"
+              "reference cycle: #{ring} — an aggregate points at another by id, and a " \
+                "ring back to where it started means no aggregate in it is a boundary " \
+                "anyone can reason about alone ; break the ring, or let one side be found " \
+                "through a query instead of a reference pointing back"
+            end
+
+            # Plain DFS with a visiting/done coloring; returns the ring in the order it
+            # closes, or nil.
+            def find_reference_cycle(edges)
+              state = {}
+
+              edges.each_key do |start|
+                cycle = reference_cycle_from(start, edges, state, [])
+                return cycle if cycle
+              end
+
+              nil
+            end
+
+            def reference_cycle_from(node, edges, state, path)
+              return nil if state[node] == :done
+              return path[path.index(node)..] if state[node] == :visiting
+
+              state[node] = :visiting
+              path.push(node)
+
+              found = first_cycle_through(edges[node], edges, state, path)
+              return found if found
+
+              path.pop
+              state[node] = :done
+              nil
+            end
+
+            def first_cycle_through(targets, edges, state, path)
+              targets.each do |target|
+                # a name this chapter never declares is dangling, not an edge
+                next unless edges.key?(target)
+
+                found = reference_cycle_from(target, edges, state, path)
+                return found if found
+              end
+
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/with_projections.rb

@@ -0,0 +1,126 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        module Validation
+          # Checks `with:` projections of policies and saga legs against the source event's shape
+          # and the target command's fields.
+          module WithProjections
+            # What every `with:` check shares: the chapter's commands by "Owner.Command", its
+            # aggregates, and the sagas' correlation heads.
+            WithContext = Struct.new(:lookup, :aggregates, :correlation_heads)
+            # One `with:` to check: the command it targets, the event it reads from, the spec
+            # itself, how a refusal names it, and the process manager when it is a saga leg.
+            WithSpec = Struct.new(:command_ref, :event_name, :with_spec, :label, :process_manager)
+            # What a `with:` source may read: the correlation key, the emitter's identity heads and
+            # the event shapes whose fields are legal.
+            Readable = Struct.new(:correlation, :identity, :shapes)
+            private_constant :WithContext, :WithSpec, :Readable
+
+            private
+
+            # Checks `with:` projections against the source event's shape and the target's fields.
+            # Same-chapter only: an unresolvable cross-chapter source or target is skipped.
+            # A for_each policy's source is a query row with no known shape, so only its target
+            # is checked.
+            def validate_with_projections!(policies, process_managers, aggregates)
+              context = WithContext.new(command_lookup(aggregates), aggregates, correlation_heads(process_managers))
+
+              policies.each { |policy| check_policy_with!(policy, context) }
+              process_managers.each do |pm|
+                pm.handlers.each do |handler|
+                  handler.dispatches.each { |dispatch| check_dispatch_with!(pm, handler, dispatch, context) }
+                end
+              end
+            end
+
+            def check_policy_with!(policy, context)
+              return if policy.with_spec.to_a.empty?
+
+              source_event = policy.for_each.to_s.empty? ? policy.on_event : nil
+              check_with_spec!(WithSpec.new(policy.trigger_command, source_event, policy.with_spec,
+                                            "#{policy.name}'s trigger", nil), context)
+            end
+
+            def check_dispatch_with!(process_manager, handler, dispatch, context)
+              return if dispatch.with_spec.to_a.empty?
+
+              label = "#{process_manager.name}'s dispatch #{dispatch.command_name}"
+              check_with_spec!(WithSpec.new(dispatch.command_name, handler.event_type, dispatch.with_spec,
+                                            label, process_manager), context)
+            end
+
+            # Checks one `with:` spec: each key must be a field the target command accepts,
+            # and each Symbol source must be the correlation key, the emitter's identity, or a
+            # field of the event's shape. A saga leg also falls back to the opening event's shape,
+            # since saga memory starts as that payload.
+            def check_with_spec!(spec, context)
+              target   = context.lookup[spec.command_ref]
+              readable = readable_sources(spec, context.aggregates)
+
+              spec.with_spec.each do |field, source|
+                refuse_undeclared_with_field!(spec, field) if target && !command_declares?(target, field, context)
+                refuse_unreadable_with_source!(spec, source, readable)
+              end
+            end
+
+            def readable_sources(spec, aggregates)
+              pm = spec.process_manager
+              event_name = spec.event_name
+              # A policy's source also carries the emitter's identity
+              # (`PolicyInterpreter#emitter_identity`); a saga leg's source
+              # (`SagaInterpreter#dispatch_args`) merges no such thing.
+              identity = pm.nil? && event_name ? event_identity_heads_for(event_name, aggregates) : []
+              shapes = [event_name && event_shape_for(event_name, aggregates),
+                        pm && event_shape_for(pm.starts_on, aggregates)].compact
+              Readable.new(pm&.correlates_by && pm.correlation_head, identity, shapes)
+            end
+
+            def refuse_undeclared_with_field!(spec, field)
+              raise Malformed,
+                    "#{spec.label}'s with: names #{field.inspect}, which #{spec.command_ref} does not declare"
+            end
+
+            def refuse_unreadable_with_source!(spec, source, readable)
+              return unless source.is_a?(::Symbol)
+              return if source == readable.correlation || readable.identity.include?(source)
+              return if readable.shapes.empty? || shape_reads?(readable.shapes, source)
+
+              raise Malformed,
+                    "#{spec.label}'s with: reads :#{source} off #{spec.event_name.inspect}, which does not declare it"
+            end
+
+            def shape_reads?(shapes, source)
+              shapes.any? { |shape| shape.any? { |name, *| name == source } }
+            end
+
+            # Mirrors `ArgumentGate#refuse_unknown_arguments`: `:id`, the owning aggregate's
+            # `identity_heads` and `Naming.reference_key(command.references)` are all legal keys
+            # beside the command's own attributes.
+            def command_declares?(command, field, context)
+              return true if plain_argument?(command, field, context)
+              return false unless command.references
+
+              referenced = context.aggregates.find { |a| a.hecks_name == command.references }
+              referenced ? referenced_key?(referenced, command, field) : false
+            end
+
+            def plain_argument?(command, field, context)
+              command.attributes.any? { |a| a.name == field } || field == :id || context.correlation_heads.include?(field)
+            end
+
+            def referenced_key?(referenced, command, field)
+              referenced.identity_heads.include?(field) || Naming.reference_key(command.references) == field
+            end
+
+            # A saga's `correlates_by` head is a legal `with:` key: correlation rides
+            # through commands that never read it.
+            def correlation_heads(process_managers)
+              process_managers.filter_map { |pm| pm.correlates_by && pm.correlation_head }
+            end
+          end
+        end
+      end
+    end
+  end
+end