hecks 3.5.0 → 3.6.0

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

@@ -1,5 +1,8 @@
 require_relative "word_gate"
 require_relative "aggregate_builder/sealing"
+require_relative "aggregate_builder/relationships"
+require_relative "aggregate_builder/rules"
+require_relative "aggregate_builder/draining"
 module Hecks
   module Bluebook
     module DSL
@@ -25,19 +28,8 @@ module Hecks
         #   entity-scoped bare given references, threaded unchanged to every entity
         def initialize(name, chapter_named_givens: {}, chapter_pending_givens: [],
                        chapter_entity_named_givens: {}, chapter_entity_pending_givens: [])
-          @name          = name
-          @value_objects = []
-          @commands      = []
-          @invariants    = []
-          @named_givens  = {}
-          @projected_fields = []
-          @identity_paths = []
-          @entities      = []
-          @queries       = []
-          @policies      = []
-          @reference_targets = []
-          # Shared unchanged with every entity/command this aggregate builds (see `#entity_impl`).
-          @entity_named_givens = {}
+          @name = name
+          start_declarations
           # Threaded in from `BluebookBuilder#aggregate`; shared chapter-wide across aggregates.
           @chapter_named_givens = chapter_named_givens
           # Threaded chapter-wide; a chapter may span multiple files (see `#pending_chapter_given`)
@@ -46,11 +38,6 @@ module Hecks
           # passed through unchanged to every entity this aggregate builds.
           @chapter_entity_named_givens   = chapter_entity_named_givens
           @chapter_entity_pending_givens = chapter_entity_pending_givens
-          # `entity`/`command`/`query` queue a descriptor here instead of building eagerly
-          # (see `#drain_pending!`).
-          @pending_entities = []
-          @pending_commands = []
-          @pending_queries  = []
         end
 
         # Sets the human-readable description shown for this aggregate.
@@ -69,104 +56,6 @@ module Hecks
           @provenance = from
         end
 
-        # Declares a reference from this aggregate's own head to another aggregate's identity.
-        #
-        # @param type [Module, Symbol, String] the referenced aggregate, written as a bare
-        #   constant
-        # @param as [Symbol, nil] the attribute's name; nil derives it from `type`
-        # @param optional [Boolean] whether the reference may be absent
-        # @return [void]
-        # @raise [Bluebook::DSL::Malformed] if `as` (or the derived name) is already declared
-        def reference_to_impl(type, as: nil, optional: false)
-          target = Naming.demodulise(type)
-          @reference_targets << target
-          relationship_attribute(target, :reference_to,
-                                 as || default_reference_name(target), optional: optional)
-        end
-
-        # Declares that this aggregate holds its own kept-fresh copy of a field reached through
-        # a reference, so a rule can read it locally instead of reaching across the boundary.
-        #
-        # `from:` names the local reference, not the target aggregate, so two references to the
-        # same aggregate can each carry their own projection.
-        #
-        # @param name [Symbol, String] the local field receiving the projected remote value
-        # @param from [Symbol, String] the local reference and remote field, dotted, such as
-        #   `:"customer.status"`
-        # @return [Array<Bluebook::ProjectedField>] every projected field declared so far, this
-        #   one last
-        # @raise [Bluebook::DSL::Malformed] if `from` is not `reference.field` shaped
-        def projects_impl(name, from:)
-          reference, _, remote_field = from.to_s.rpartition(".")
-
-          if reference.empty? || remote_field.empty?
-            raise Malformed,
-                  "#{@name}.projects :#{name} names #{from.inspect}, which is not " \
-                  "reference.field — say which reference and which field on it, e.g. " \
-                  "from: :\"customer.status\""
-          end
-
-          @projected_fields << ProjectedField.new(name: name.to_sym, reference: reference.to_sym,
-                                                  remote_field: remote_field.to_sym)
-        end
-
-        # Declares a list-typed relationship to another aggregate, referenced by its plural name.
-        #
-        # Under `MetaValidator.shadow_parsing?`, routes to the collapsing single-reference
-        # form instead, so frozen era text keeps its original meaning.
-        #
-        # @param type [Module, Symbol, String] the related aggregate's plural name, a bare constant
-        # @param as [Symbol, nil] the attribute's name; nil derives it from `type`
-        # @param legacy_options [Hash] must be empty outside shadow-parsing; under
-        #   shadow-parsing, `:optional` is read for the legacy single-reference form
-        # @return [void]
-        # @raise [Bluebook::DSL::Malformed] outside shadow-parsing, if non-empty, or if the
-        #   derived name is already declared
-        def has_many_impl(type, as: nil, **legacy_options)
-          return legacy_has_many(type, as: as, optional: legacy_options.fetch(:optional, false)) if MetaValidator.shadow_parsing?
-
-          unless legacy_options.empty?
-            raise Malformed,
-                  "#{@name}.has_many takes no #{legacy_options.keys.first}: — an empty list already means none"
-          end
-
-          plural = Naming.demodulise(type)
-          target = Naming.singularize(plural)
-          @reference_targets << target
-          relationship_attribute(target, :has_many, as || Naming.snake(plural).to_sym,
-                                 list: true)
-        end
-
-        # Declares a single-valued relationship this aggregate holds toward another.
-        #
-        # @param type [Module, Symbol, String] the related aggregate, a bare constant
-        # @param as [Symbol, nil] the attribute's name; nil derives it from `type`
-        # @param optional [Boolean] whether the relationship may be absent
-        # @return [void]
-        def has_one_impl(type, as: nil, optional: false)
-          return legacy_has_one(type, as: as, optional: optional) if MetaValidator.shadow_parsing?
-
-          target = Naming.demodulise(type)
-          @reference_targets << target
-          relationship_attribute(target, :has_one, as || Naming.snake(target).to_sym,
-                                 optional: optional)
-        end
-
-        # Declares a single-valued relationship toward the aggregate that owns this one.
-        #
-        # @param type [Module, Symbol, String] the owning aggregate, a bare constant
-        # @param as [Symbol, nil] the attribute's name; nil derives it from `type`
-        # @param optional [Boolean] whether the relationship may be absent
-        # @return [void]
-        def belongs_to_impl(type, as: nil, optional: false)
-          return legacy_has_one(type, as: as, optional: optional) if MetaValidator.shadow_parsing?
-
-          target = Naming.demodulise(type)
-          @reference_targets << target
-          relationship_attribute(target, :belongs_to, as || Naming.snake(target).to_sym,
-                                 optional: optional)
-        end
-
         # Declares this aggregate's own state machine.
         #
         # @param field [Symbol, String] the attribute the state machine lives on
@@ -178,24 +67,6 @@ module Hecks
           @lifecycle = LifecycleBuilder.build(field, default: default, &)
         end
 
-        # Queues a piece nested in this aggregate, built later once every sibling has been seen.
-        #
-        # @param name [String] the nested piece's name
-        # @yield the piece body, evaluated against an `EntityBuilder` once drained
-        # @return [Array<Array>] every pending piece queued so far, this one last
-        def entity_impl(name, &block)
-          @pending_entities << [name, block]
-        end
-
-        # Queues a query declared on this aggregate, built later once every sibling has been seen.
-        #
-        # @param name [String] the query's name
-        # @yield the query body, evaluated against a `QueryBuilder` once drained
-        # @return [Array<Array>] every pending query queued so far, this one last
-        def query_impl(name, &block)
-          @pending_queries << [name, block]
-        end
-
         # Declares a policy scoped to this aggregate, stamping it with the aggregate's own name.
         #
         # @param name [String] the policy's name
@@ -217,12 +88,7 @@ module Hecks
         # @return [Array<Bluebook::ValueObject>] this one, plus any closed sets synthesised
         # @raise [Bluebook::DSL::Malformed] if both `type` and a block are given, or the body fails
         def value_object(name, type = nil, &block)
-          if type && block
-            raise Malformed,
-                  "#{name} declares both a type (#{type.inspect}) and a block — " \
-                  "value_object #{name.inspect}, Type is sugar for a block declaring " \
-                  "exactly one attribute named :value; write one form or the other, never both"
-          end
+          refuse_type_and_block!(name, type, block)
 
           builder = ValueObjectBuilder.new(name, owner_value_objects: @value_objects + closed_sets)
           builder.attribute_impl(:value, type) if type
@@ -231,96 +97,6 @@ module Hecks
           @value_objects.concat(builder.closed_sets)
         end
 
-        # Queues a command declared on this aggregate, built later once every sibling has been
-        # seen.
-        #
-        # `from:` is checked against this aggregate's own lifecycle field, never a target
-        # state or transition, so a guard can't drift out of sync with the state machine.
-        #
-        # @param name [String] the command's name
-        # @param from [String, Symbol, Array<String, Symbol>, nil] the lifecycle state(s) this
-        #   command guards from; nil admits from any state
-        # @yield the command body, evaluated against a `CommandBuilder` once drained
-        # @return [Array<Array>] every pending command queued so far, this one last
-        def command_impl(name, from: nil, &block)
-          # Owner is stamped once `Aggregate#initialize` runs; an entity's own commands are
-          # owned by the entity instead.
-          @pending_commands << [name, from, block]
-        end
-
-        # Declares a rule this aggregate's own commands must satisfy, or references a sibling's.
-        # `declared_by:` disambiguates a bare reference when two aggregates share a description.
-        #
-        # @param description [String] the rule's description; also its name for a sibling reference
-        # @param declared_by [Module, Symbol, String, nil] which aggregate's rule; only meaningful
-        #   with no block
-        # @yield the predicate body; evaluated for its extracted source, never called directly
-        # @return [void]
-        # @raise [Bluebook::DSL::Malformed] if the source can't be extracted, or a bare reference
-        #   resolves to none or more than one candidate once the chapter has loaded
-        def given_impl(description, declared_by: nil, &predicate)
-          return reference_named_chapter_given(description, declared_by: declared_by) unless predicate
-
-          named = build_rule(Given, description, predicate, owner_name: @name, word: "given",
-                              extraction_failure: "its source could not be read, so no other runtime could ever evaluate it")
-          @named_givens[description] = named
-          # Keyed by [description, this aggregate's name] so two aggregates sharing a
-          # description are distinct candidates, never merged into one slot.
-          @chapter_named_givens[description] ||= {}
-          @chapter_named_givens[description][@name] ||= named
-        end
-
-        private
-
-        # Unresolved (no candidate yet) doesn't raise here — a chapter split across files
-        # may still declare this precondition in a later file (see `#pending_chapter_given`).
-        def reference_named_chapter_given(description, declared_by:)
-          verify_resolves_via!("given", "Aggregate", "owner_keyed")
-          candidates = resolve_owner_keyed(@chapter_named_givens, description)
-
-          named =
-            if declared_by
-              owner = Naming.demodulise(declared_by)
-              candidates[owner] || pending_chapter_given(description, declared_by: owner)
-            elsif candidates.size == 1
-              candidates.values.first
-            elsif candidates.empty?
-              pending_chapter_given(description, declared_by: nil)
-            else
-              raise(Malformed,
-                    "#{@name}'s given #{description.inspect} is ambiguous in this chapter — " \
-                    "#{candidates.keys.join(', ')} each declare a DIFFERENT predicate under " \
-                    "this same description; name which one with declared_by: (e.g. " \
-                    "given(#{description.inspect}, declared_by: #{candidates.keys.first}))")
-            end
-
-          @named_givens[description] = named
-        end
-
-        # Returns a placeholder `Given`, embedded by reference in this aggregate's IR;
-        # `BluebookBuilder#resolve_pending_chapter_givens!` mutates it in place once the
-        # whole chapter loads, so every existing reference sees the resolved fields together.
-        def pending_chapter_given(description, declared_by:)
-          placeholder = Given.new(description: description, canonical: nil, predicate: nil)
-          @chapter_pending_givens << { aggregate: @name, description: description,
-                                        declared_by: declared_by, placeholder: placeholder }
-          placeholder
-        end
-
-        public
-
-        # Declares a rule the whole aggregate must satisfy, checked after every command, before
-        # save.
-        #
-        # @param description [String] the rule's description
-        # @yield the predicate body; evaluated for its extracted source, never called directly
-        # @return [void]
-        # @raise [Bluebook::DSL::Malformed] if the block's source could not be extracted
-        def invariant_impl(description, &predicate)
-          @invariants << build_rule(Invariant, description, predicate, owner_name: @name, word: "invariant",
-                                     extraction_failure: "it would be a rule the IR cannot carry")
-        end
-
         # Assembles every declared attribute, construct and rule into an `Aggregate`, after
         # draining pending commands/queries/entities and running every `seal_*` check.
         #
@@ -332,30 +108,9 @@ module Hecks
         def build
           drain_pending!
           resolve_pending_identity!
-          seal_mutation_targets
-          seal_query_targets
-          seal_defaults
-          seal_lifecycle_guards
-          seal_projected_fields
-          seal_correction_targets
+          seal_all
 
-          ir = Aggregate.new(
-            name:              @name,
-            description:       @description,
-            attributes:        attributes,
-            value_objects:     @value_objects + closed_sets,
-            commands:          @commands,
-            invariants:        @invariants,
-            preconditions:     @named_givens.values,
-            projected_fields:  @projected_fields,
-            identified_by:     @identity_paths,
-            lifecycle:         @lifecycle,
-            entities:          @entities,
-            queries:           @queries,
-            policies:          @policies,
-            reference_targets: @reference_targets + entity_reference_targets,
-            provenance:        @provenance
-          )
+          ir = Aggregate.new(**aggregate_shape, **aggregate_rules)
 
           # On purpose, after the IR exists: the object the IR graph should know is `ir`,
           # not this builder.
@@ -380,30 +135,51 @@ module Hecks
 
         private
 
-        # Deferred: entity/command/query queue a descriptor instead of building eagerly, so a
-        # later-declared piece can still be referenced from an earlier line. Entities drain
-        # first and fully — a command's own `sets` may need an entity's attributes already built.
-        def drain_pending!
-          @entities = @pending_entities.map do |name, block|
-            EntityBuilder.build(name, owner_value_objects:             @value_objects + closed_sets,
-                                      owner_named_givens:              @entity_named_givens,
-                                      identity_name_prefix:            "#{Naming.demodulise(@name)}#{Naming.demodulise(name)}",
-                                      identity_value_object_installer: ->(value_object) { @value_objects << value_object },
-                                      aggregate_name:                  @name,
-                                      chapter_entity_named_givens:     @chapter_entity_named_givens,
-                                      chapter_entity_pending_givens:   @chapter_entity_pending_givens,
-                                &block)
-          end
+        def start_declarations
+          @value_objects     = []
+          @invariants        = []
+          @named_givens      = {}
+          @projected_fields  = []
+          @identity_paths    = []
+          @policies          = []
+          @reference_targets = []
+          start_pending
+        end
 
-          @commands = @pending_commands.map do |name, from, block|
-            CommandBuilder.build(name, owner: @name, from: from, named_givens: @named_givens,
-                                        owner_attributes: attributes,
-                                        owner_constructs: @value_objects + closed_sets + @entities, &block)
-          end
+        def start_pending
+          # Shared unchanged with every entity/command this aggregate builds (see `#entity_impl`).
+          @entity_named_givens = {}
+          # `entity`/`command`/`query` queue a descriptor here instead of building eagerly
+          # (see `#drain_pending!`).
+          @pending_entities = []
+          @pending_commands = []
+          @pending_queries  = []
+          @entities = []
+          @commands = []
+          @queries  = []
+        end
 
-          @queries = @pending_queries.map do |name, block|
-            QueryBuilder.build(name, owner_attributes: attributes, &block)
-          end
+        def refuse_type_and_block!(name, type, block)
+          return unless type && block
+
+          raise Malformed,
+                "#{name} declares both a type (#{type.inspect}) and a block — " \
+                "value_object #{name.inspect}, Type is sugar for a block declaring " \
+                "exactly one attribute named :value; write one form or the other, never both"
+        end
+
+        # The aggregate's name and the state it holds.
+        def aggregate_shape
+          { name: @name, description: @description, attributes: attributes,
+            value_objects: @value_objects + closed_sets, identified_by: @identity_paths,
+            lifecycle: @lifecycle, entities: @entities, provenance: @provenance }
+        end
+
+        # What the aggregate does and the rules it keeps.
+        def aggregate_rules
+          { commands: @commands, invariants: @invariants, preconditions: @named_givens.values,
+            projected_fields: @projected_fields, queries: @queries, policies: @policies,
+            reference_targets: @reference_targets + entity_reference_targets }
         end
 
         # `identified_by`'s resolution pool: an aggregate resolves a bare field's value-object
@@ -415,16 +191,6 @@ module Hecks
         def install_identity_value_object!(value_object)
           @value_objects << value_object
         end
-
-        # Shadow-parsing's collapsing behavior for has_many/has_one/belongs_to.
-        def legacy_has_many(type, as:, optional: false)
-          plural = Naming.demodulise(type)
-          reference_to_impl(Naming.singularize(plural), as: as || Naming.snake(plural).to_sym, optional: optional)
-        end
-
-        def legacy_has_one(type, as:, optional: false)
-          reference_to_impl(type, as: as || Naming.snake(Naming.demodulise(type)).to_sym, optional: optional)
-        end
       end
     end
   end

data/lib/hecks/bluebook/dsl/attribute_collector/identity_resolution.rb

@@ -0,0 +1,113 @@
+module Hecks
+  module Bluebook
+    module DSL
+      module AttributeCollector
+        # Expands an `identified_by` declaration into the scalar paths that make up an identity:
+        # a named attribute, or a value object minted as one structured field, walked down to
+        # its scalar leaves.
+        module IdentityResolution
+          private
+
+          # Each selected identity head contributes all its scalar leaves in declaration order.
+          def resolve_identity_field!(field, value_objects, context_name)
+            attr = attributes.find { |a| a.name == field }
+
+            # A bare `:id` or `_id`-suffixed name with no matching attribute is the walk-parent/
+            # fallback-identity convention (Instance#materialize_identity! falls back to `:id`).
+            return [field.to_s] if attr.nil? && (field.to_s == "id" || field.to_s.end_with?("_id"))
+
+            raise Malformed, "#{context_name}.identified_by :#{field} names no attribute #{context_name} declares" unless attr
+
+            identity_paths_for_attribute(attr, value_objects, context_name, field.to_s, [])
+          end
+
+          # A named or inline identity mints one structured field, then expands
+          # each scalar leaf beneath it into the existing path-shaped IR.
+          def resolve_identity_type!(type, as, insert_at, value_objects, context_name)
+            target = Naming.demodulise(type.respond_to?(:hecks_name) ? type.hecks_name : type)
+            vo = identity_value_object(type, target, value_objects, context_name)
+            field = (as || Naming.snake(target)).to_sym
+            refuse_declared_identity_field!(field, target, context_name)
+
+            insert_identity_attribute(field, target, insert_at)
+            vo.attributes.flat_map do |attribute|
+              identity_paths_for_attribute(attribute, value_objects, context_name,
+                                           "#{field}.#{attribute.name}", [target])
+            end
+          end
+
+          def identity_value_object(type, target, value_objects, context_name)
+            matches = value_objects.select { |value_object| value_object.hecks_name.to_s == target }
+            raise Malformed, "#{context_name}.identified_by names duplicate value object #{target}" if matches.size > 1
+
+            vo = type.respond_to?(:attributes) ? type : matches.first
+            raise Malformed, "#{context_name}.identified_by names #{target}, which is not a declared value object" unless vo
+            raise Malformed, "#{context_name}.identified_by names #{target}, which declares no attributes" if vo.attributes.empty?
+
+            vo
+          end
+
+          def refuse_declared_identity_field!(field, target, context_name)
+            return unless attributes.any? { |attribute| attribute.name == field }
+
+            raise Malformed,
+                  "#{context_name}.identified_by #{target} mints :#{field}, but that attribute is already declared"
+          end
+
+          # `Attribute.new` directly: the value object is an anonymous class whose `to_s` would
+          # spell "#<Class:0x...>", so the demodulised `target` text is the type. The attribute
+          # is moved to `insert_at`, the attribute count when `identified_by` was called;
+          # resolution runs at build time, so appending would put the identity field last.
+          def insert_identity_attribute(field, target, insert_at)
+            attributes << Attribute.new(name: field, type: target)
+            attributes.insert(insert_at, attributes.pop)
+          end
+
+          def identity_paths_for_attribute(attribute, value_objects, context_name, path, visited)
+            refuse_unfit_identity_member!(attribute, context_name, path)
+            return [path] if attribute.reference?
+
+            nested = value_objects.find { |value_object| value_object.hecks_name.to_s == attribute.type.to_s }
+            return [path] unless nested
+
+            refuse_identity_cycle!(nested, visited, context_name)
+            refuse_compound_identity!(nested, path, context_name)
+
+            member = nested.attributes.first
+            identity_paths_for_attribute(member, value_objects, context_name, "#{path}.#{member.name}",
+                                         [*visited, nested.hecks_name.to_s])
+          end
+
+          def refuse_unfit_identity_member!(attribute, context_name, path)
+            if attribute.list?
+              raise Malformed,
+                    "#{context_name}'s identity member #{path} is a list — an identity member must be scalar"
+            end
+            return unless attribute.optional?
+
+            raise Malformed,
+                  "#{context_name}'s identity member #{path} is optional — an identity must be wholly known"
+          end
+
+          def refuse_identity_cycle!(nested, visited, context_name)
+            return unless visited.include?(nested.hecks_name.to_s)
+
+            cycle = [*visited, nested.hecks_name.to_s].join(" -> ")
+            raise Malformed, "#{context_name}'s identity value objects form a cycle: #{cycle}"
+          end
+
+          # A bare field derives one scalar, so each value object on the way must wrap exactly one
+          # field (ADR 0025); otherwise it would silently mint an unannounced compound key.
+          def refuse_compound_identity!(nested, path, context_name)
+            return if nested.attributes.size == 1
+
+            candidates = nested.attributes.map(&:name).join(", ")
+            raise Malformed,
+                  "#{context_name}.identified_by :#{path} names #{nested.hecks_name}, which has " \
+                  "#{nested.attributes.size} field#{"s" unless nested.attributes.size == 1} (#{candidates})"
+          end
+        end
+      end
+    end
+  end
+end