hecks 3.5.0 → 3.6.0

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

@@ -1,3 +1,8 @@
+require_relative "judge/identity"
+require_relative "judge/dispatching"
+require_relative "judge/walking"
+require_relative "judge/cells"
+
 module Hecks
   module Bluebook
     module MetaValidator
@@ -6,6 +11,10 @@ module Hecks
       # un-offered by omission.
       class Judge
         include Readings
+        include Identity
+        include Dispatching
+        include Walking
+        include Cells
 
         # ValueObject before Entity: an entity's own attributes may
         # reference a value object, which must exist before it resolves.
@@ -16,401 +25,47 @@ module Hecks
         # command's one `*_id` argument and cannot express a second parent.
         WITHIN_ENTITY = %w[Command Query].freeze
 
-        attr_reader :refusals
-
-        # The runtime dispatched into, not just the refusals, so a caller
-        # can read the resulting records back out.
-        attr_reader :runtime
-
-        def initialize(bluebook)
-          @bluebook = bluebook
-          @refusals = []
-          @runtime  = MetaValidator.fresh_runtime
-          @plan     = Plan.for(MetaValidator.grammar_registry)
-          judge!
-        end
-
-        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
-
-        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
-
-        # 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
-
-        def judge!
-          declare_node("Bluebook", @bluebook, nil, 0)
-          detail_node("Bluebook", @bluebook, nil, 0)
-        end
-
-        # 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(category, node, parent_id, index, extra = {}, receiver: nil)
-          plan = @plan.category(category)
-          return unless plan
-
-          declare(plan, category, node, identify(category, parent_id, node, index), parent_id, index, extra)
-        end
-
-        def detail_node(category, node, parent_id, index, extra = {}, receiver: nil)
-          plan = @plan.category(category)
-          return unless plan
-
-          id = identify(category, parent_id, node, index)
-          # `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, category, node, index, parent_id))
-          receiver   ||= { aggregate: id, entities: [] }
-          eager, later = children_of(category).partition { |child| eager?(category, child) }
-          # `children_of`'s order is incidental (plan registration order);
-          # keep only what EAGER_CHILDREN promises, in the order it does.
-          eager = Array(EAGER_CHILDREN[category]) & eager
-
-          eager.each { |child| walk_all(child, node, id, entity_child_extra(child, identity), receiver: receiver) }
-          setters(plan, category, node, receiver)
-          # Before `appends`: a nested entity referenced from this node's
-          # own attribute list must exist before that list is walked.
-          nest_entities(category, node, id, parent_id)
-          appends(plan, category, node, receiver, parent_id)
-          later.each { |child| walk_all(child, node, id, entity_child_extra(child, identity), receiver: receiver) }
-          within_entity(category, node, id, parent_id)
-          sealers(plan, category, receiver)
-        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
-
-        # 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, category, node, index, parent_id)
-          plan.identity_paths.each_with_object({}) do |path, fields|
-            head = path.to_s.split(".").first
-            next if head == OWNER
-
-            if head == POSITION
-              fields[head.to_sym] = v(index)
-            else
-              raw = head == plan.parent_key.to_s ? parent_id : field_value(category, node, head.to_sym, parent_id)
-              fields[head.to_sym] = carried(plan, plan.declare, head, raw)
-            end
-          end
-        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
-
-        def walk_all(category, node, parent_id, extra = {}, receiver: nil)
-          reader = collection_reader(category)
-          return unless node.respond_to?(reader)
-
-          children = Array(node.public_send(reader))
-          children.each_with_index { |child, index| declare_node(category, child, parent_id, index, extra) }
-          children.each_with_index do |child, index|
-            child_plan = @plan.category(category)
-            child_receiver = if child_plan&.entity_owned
-                               child_id = identify(category, parent_id, child, index)
-                               root = receiver || { aggregate: parent_id, entities: [] }
-                               { aggregate: root[:aggregate], entities: Array(root[:entities]) + [child_id] }
-                             end
-            detail_node(category, child, parent_id, index, extra, receiver: child_receiver)
-          end
-        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(category, node, id, aggregate)
-          return unless category == "Entity"
-
-          WITHIN_ENTITY.each do |child|
-            plan = @plan.category(child)
-            walk_all(child, node, id, {
-                       aggregate: carried(plan, plan&.declare, "aggregate", aggregate),
-                       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(category, node, id, aggregate)
-          return unless category == "Entity"
-
-          plan = @plan.category("Entity")
-          walk_all("Entity", node, aggregate, {
-                     aggregate: carried(plan, plan&.declare, "aggregate", aggregate),
-                     owner:     carried(plan, plan&.declare, "owner", id)
-                   })
-        end
-
         # Where a node sits among siblings is a fact about the walk, not
         # the node, so the walk supplies it rather than reading a stored
         # field; Reconstruction depends on this being the source order.
-        # `private` above has no effect on a constant; kept here anyway,
-        # beside the method that reads it.
-        # rubocop:disable-next Lint/UselessConstantScoping
         POSITION = "position".freeze
 
-        def declare(plan, category, node, id, parent_id, index, extra = {})
-          return unless plan.declare
-
-          payload = {}
-          payload[plan.parent_key.to_sym] = carried(plan, plan.declare, plan.parent_key, parent_id) if plan.parent_key
-          plan.fields.each do |field|
-            payload[field.to_sym] = if field == POSITION
-                                      v(index)
-                                    else
-                                      carried(plan, plan.declare, field, field_value(category, node, field.to_sym, parent_id))
-                                    end
-          end
-
-          send_to("Bluebook::#{verb_for(plan, plan.declare)}", id, to: id, **payload.merge(extra))
-        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, category, node, receiver)
-          plan.setters.each do |setter|
-            payload = setter.targets.to_h do |target, argument|
-              [argument.to_sym, v(setter_value(category, 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, category, node, receiver, parent_id)
-          id = receiver[:entities].last || receiver[:aggregate]
-          owner_id = owning_aggregate_ref(category, id, parent_id)
-          plan.appends.each do |list_name, append|
-            rows_for(category, list_name, node).each_with_index do |row, index|
-              chosen = append_for(category, list_name, append, row, node)
-              # `position` is the walk index, as in `declare`: an appended
-              # element is ordered by where the walk found it.
-              payload = chosen.map.to_h do |field, argument|
-                value = if field.to_s == POSITION
-                          v(index)
-                        else
-                          carried(@plan.category(category), chosen.verb, argument,
-                                  cell(category, list_name, row, field, id, chosen, owner_id))
-                        end
-                [argument.to_sym, value]
-              end
-
-              send_to("Bluebook::#{verb_for(plan, chosen.verb)}", "#{id}##{list_name}[#{index}]",
-                      to: address(receiver), **payload)
-            end
-          end
-        end
-
-        # An entity has no value objects of its own; its attributes
-        # resolve against its enclosing aggregate's pool, so the root
-        # aggregate id (`parent_id`, not the direct parent) is what this
-        # returns for it.
-        def owning_aggregate_ref(category, id, parent_id)
-          category == "Entity" ? parent_id : id
-        end
-
-        def sealers(plan, _category, receiver)
-          id = receiver[:entities].last || receiver[:aggregate]
-          plan.sealers.each { |verb| send_to("Bluebook::#{verb_for(plan, verb)}", id, to: address(receiver)) }
-        end
-
-        # An attribute's type is offered as the id of the value object it
-        # names, so "attributes must use value-object types" is enforced
-        # by reference resolution rather than a predicate — for an
-        # entity's own attributes too, since an entity is its own root.
-        def cell(category, list_name, row, field, id, append, aggregate_id)
-          value = row_value(row, field)
-          # A default keeps its type by being written as a literal (0.0,
-          # not "0.0"): the language holds it as text, and text alone forgets.
-          return encode_literal(value) if field == :default
-          return value unless field == :type
-          # A reference names another head wherever it's written (on a
-          # head, a command, a piece, or an ask), so it's offered as that
-          # head's id in all four; only a head's own attributes further
-          # qualify a plain type into a value object's id.
-          return points_at(row, id) if append.verb == "Reference"
-          return value unless attribute_list?(category, list_name)
-
-          Naming.identity([owning_aggregate_id(aggregate_id, value), value])
-        end
-
-        # A head's own attributes (an aggregate's, or an entity's own
-        # root). Every other "attributes" list belongs to something that
-        # isn't a head, so a type written there is a name, not a reference.
-        def attribute_list?(category, list_name)
-          list_name.to_s == "attributes" && %w[Aggregate Entity].include?(category)
-        end
-
-        # A value object's type may be declared on a different aggregate
-        # in the same chapter; the local aggregate is tried first, then
-        # the first (declaration-order) other aggregate that declares it.
-        def owning_aggregate_id(id, value)
-          local = @bluebook.aggregates.find { |aggregate| Naming.identity([@bluebook.name, aggregate.name]) == id }
-          return id unless local
-          return id if names?(local, value)
-
-          owner = @bluebook.aggregates.find { |aggregate| aggregate != local && names?(aggregate, value) }
-          return id unless owner
-
-          Naming.identity([@bluebook.name, owner.name])
-        end
-
-        # Checks both value objects and entities this aggregate declares:
-        # the caller already knows which verb it dispatches, not which
-        # collection to search, without re-deriving that here.
-        def names?(aggregate, value)
-          aggregate.value_objects.any? { |vo| vo.hecks_name == value } ||
-            aggregate.entities.any? { |entity| entity.hecks_name == value }
-        end
-
-        # The row itself decides which verb an attribute belongs to:
-        # Attribute for a value-object type, Reference<X> for another
-        # aggregate's head, Holds for an entity this aggregate declares.
-        # Each alternate carries its own field map — borrowing the
-        # primary's would dispatch `type:` where Reference declares
-        # `points_at:`.
-        def append_for(category, list_name, append, row, node)
-          return append unless list_name.to_s == "attributes"
-          return alternate(category, "Reference") || append if reference_row?(row)
-          return alternate(category, "Holds") || append if entity_row?(row, node)
-
-          append
-        end
-
-        def alternate(category, verb)
-          @plan.category(category).alternates.find { |append| append.verb == verb }
-        end
-
-        def reference_row?(row) = row.respond_to?(:reference?) && row.reference?
-
-        # Only a head declares pieces; since every attribute list reaches
-        # here now, `node` may be a command, a piece or an ask, none of
-        # which answer `entities`.
-        def entity_row?(row, node)
-          return false unless node.respond_to?(:entities)
-
-          Array(node.entities).any? { |entity| entity.hecks_name == row.type.to_s }
-        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(category, parent_id, node, index)
-          plan = @plan.category(category)
-          return declared_name(node) unless plan
-
-          Naming.identity(plan.identity_paths.map { |path| identity_part(plan, path, parent_id, node, index, category) })
-        end
-
         # `owner_id` is a second reserved head (beside `position`): it
         # names whichever record is walking this one right now, aggregate
         # or entity, so Command/Query address the right piece. It is
         # never a declared attribute, so it can't be read through
         # `field_value`.
-        # `private` above has no effect on a constant; kept here anyway,
-        # beside the method that reads it.
-        # rubocop:disable-next Lint/UselessConstantScoping
         OWNER = "owner_id".freeze
 
-        def identity_part(plan, path, parent_id, node, index, category)
-          head = path.to_s.split(".").first
-          return parent_id.to_s if head == plan.parent_key.to_s || head == OWNER
-          return index.to_s     if head == POSITION
+        # Where the walk stands: the node being offered, its category, the id of the record that
+        # holds it and its position among its siblings.
+        Visit = Struct.new(:category, :node, :parent_id, :index)
 
-          v_scalar(field_value(category, node, head.to_sym, parent_id))
-        end
+        # One element of an appended list: the list it joins, the row, its position, the id of the
+        # record appended onto and the aggregate its value-object types resolve against.
+        Appending = Struct.new(:list_name, :append, :row, :index, :id, :owner_id)
 
-        # 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)
+        attr_reader :refusals
 
-          held.to_h.values.first.to_s
-        end
+        # The runtime dispatched into, not just the refusals, so a caller
+        # can read the resulting records back out.
+        attr_reader :runtime
 
-        def children_of(category)
-          @plan.names.select { |name| @plan.category(name).parent == category }
+        def initialize(bluebook)
+          @bluebook = bluebook
+          @refusals = []
+          @runtime  = MetaValidator.fresh_runtime
+          @plan     = Plan.for(MetaValidator.grammar_registry)
+          judge!
         end
 
-        def eager?(category, child) = Array(EAGER_CHILDREN[category]).include?(child)
+        private
 
-        # 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))
+        def judge!
+          visit = Visit.new("Bluebook", @bluebook, nil, 0)
+          declare_node(visit)
+          detail_node(visit)
+        end
       end
     end
   end

data/lib/hecks/bluebook/meta_validator/modes.rb

@@ -0,0 +1,137 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      # The mode switches of judging: bootstrapping, deferring, disabled, shadow-parsing and the
+      # forced fixpoint. `MetaValidator` extends this, so each reads and writes its own state.
+      module Modes
+        # Whether the language's own grammar is still loading raw, unjudged.
+        # Judging it while it loads would recurse, so the bootstrap sets this
+        # and the fixpoint clears it once every grammar file is merged.
+        #
+        # @return [Boolean]
+        def bootstrapping? = @bootstrapping
+
+        # Whether `call` is queuing chapters instead of judging them, while a
+        # chapter's own files are still being merged (see `defer`).
+        #
+        # @return [Boolean]
+        def deferring? = @deferring
+
+        # Queues every chapter `call` sees while the block runs, instead of
+        # judging them immediately (see `deferred_chapters`).
+        #
+        # @yield the caller's own load of every file in one chapter window
+        # @return [Object] the block's own return value
+        def defer
+          previous   = @deferring
+          @deferring = true
+          yield
+        ensure
+          @deferring = previous
+        end
+
+        # The chapters queued while `defer`'s block ran, awaiting
+        # `judge_deferred!`.
+        #
+        # @return [Array<String>] each deferred chapter's own `hecks_name`,
+        #   queued during the current or most recent `defer` window
+        def deferred_chapters = @deferred_chapters ||= []
+
+        # Judges every chapter queued by `defer`, once each, then clears the
+        # queue.
+        #
+        # @param registry [Runtime::Registry, nil] the registry to judge
+        #   against; a no-op if `nil`
+        # @return [void]
+        # @raise [DSL::Malformed] if a chapter's own whole-chapter battery
+        #   (`BluebookBuilder.validate_assembled!`) or the meta-domain itself
+        #   (`call`) refuses it
+        def judge_deferred!(registry)
+          pending = deferred_chapters.uniq
+          @deferred_chapters = []
+          return unless registry
+
+          pending.each { |name| judge_chapter!(registry, name) }
+        end
+
+        # Judges one deferred chapter once its own files are all merged.
+        #
+        # @param registry [Runtime::Registry] the registry holding the chapter
+        # @param name [String] the chapter's `hecks_name`
+        # @return [void]
+        def judge_chapter!(registry, name)
+          chapter = registry.bluebook(name)
+          return unless chapter
+
+          # Bare chapter-level givens must resolve before anything below
+          # reads a `Given`'s fields. The `raise` block never runs — this
+          # chapter's builder is always already open by the time `chapter` exists.
+          builder = registry.bluebook_builder(name) { raise "internal: no open builder for #{name}" }
+          builder.resolve_pending_chapter_givens!
+          # Same, one level down: entity-scoped pending givens.
+          builder.resolve_pending_chapter_entity_givens!
+
+          # Whole-chapter checks (hops, projected fields, event shapes) were
+          # skipped per file while deferring; `chapter` now holds every
+          # file's declarations, so they run once here instead of per file.
+          DSL::BluebookBuilder.validate_assembled!(chapter)
+          registry.add_bluebook(call(chapter))
+        end
+
+        # Whether meta-domain judging is off (ignored while a fixpoint build
+        # is forced).
+        # Stack-restored, not a bare flag, so a disabled window can never
+        # leak past its own scope.
+        #
+        # @return [Boolean]
+        def disabled? = @disabled && !@forcing_fixpoint
+
+        # Runs `block` with `disabled?` true, restoring it afterward — for a
+        # growth spec that boots a scratch bluebook without validation overhead.
+        #
+        # @yield the caller's own boot, with `disabled?` true throughout
+        # @return [Object] the block's own return value
+        def while_disabled
+          previous  = @disabled
+          @disabled = true
+          yield
+        ensure
+          @disabled = previous
+        end
+
+        # (ADR 0025) Whether frozen era text is currently being shadow-parsed
+        # by `EraGuard`. Judging it again here would refuse history whenever a
+        # spelling it used gets removed from the live grammar.
+        #
+        # @return [Boolean]
+        def shadow_parsing? = @shadow_parsing
+
+        # Wraps `block` with `shadow_parsing?` true, restoring it afterward.
+        #
+        # @yield the caller's own shadow-parse of one piece of frozen era text
+        # @return [Object] the block's own return value
+        def while_shadow_parsing
+          previous        = @shadow_parsing
+          @shadow_parsing = true
+          yield
+        ensure
+          @shadow_parsing = previous
+        end
+
+        # Wraps `block` with `disabled?` forced false, restoring it afterward.
+        # Only `grammar_registry`'s one-time fixpoint build uses this.
+        #
+        # @yield the one-time fixpoint build, with `disabled?` forced false
+        #   throughout
+        # @return [Object] the block's own return value
+        def while_forcing_fixpoint
+          previous          = @forcing_fixpoint
+          @forcing_fixpoint = true
+          yield
+        ensure
+          @forcing_fixpoint = previous
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/meta_validator/plan/category.rb

@@ -0,0 +1,44 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      class Plan
+        # One append command: the verb, and the value-object-field -> argument map.
+        # `:map` shadows Enumerable#map on purpose; spec/plan_spec.rb asserts on it.
+        # rubocop:disable-next Lint/StructNewOverride
+        Append = Struct.new(:verb, :map, keyword_init: true)
+
+        # One setting command. `targets` is target -> argument ; Lifecycle sets two
+        # fields in a single command, so it is a map rather than a pair.
+        Setter = Struct.new(:verb, :targets, keyword_init: true)
+
+        Category = Struct.new(:name, :declare, :parent, :parent_key, :fields,
+                              :appends, :alternates, :setters, :sealers, :references,
+                              :identity_paths, :entity_owned,
+                              keyword_init: true) do
+          # Every verb this category declares, in declaration order; a verb missing
+          # here is one the coverage gate stops watching.
+          #
+          # @return [Array<String>] every command name this category declares
+          #   (the creating command, every setter, appender, alternate
+          #   appender, and sealer), `nil` entries dropped
+          def verbs
+            [declare, *setters.map(&:verb), *appends.values.map(&:verb),
+             *alternates.map(&:verb), *sealers].compact
+          end
+
+          # Whether `argument` on `verb` carries an ID rather than a value.
+          #
+          # @param verb [String] the command name declaring `argument`
+          # @param argument [String] the argument name to check
+          # @return [Boolean] whether `argument` on `verb` is a reference
+          def references?(verb, argument)
+            Array(references[verb.to_s]).include?(argument.to_s)
+          end
+
+          # Whether this category has no parent — the root of the containment tree.
+          def root? = parent.nil?
+        end
+      end
+    end
+  end
+end