hecks 3.5.0 → 3.6.0

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

@@ -0,0 +1,73 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      class Plan
+        # Sorts a category's commands by what they do: set a field, append to a list, seal the
+        # record or carry a reference.
+        module Verbs
+          private
+
+          # Which arguments of which verbs carry an ID, read straight off the IR.
+          def references_in(commands)
+            commands.each_with_object({}) do |command, found|
+              named = command.attributes.select(&:reference?).map { |attribute| attribute.name.to_s }
+              found[command.hecks_name] = named unless named.empty?
+            end
+          end
+
+          # Every reference argument is dropped, not just the parent link:
+          # a reference is not a field.
+          def declared_fields(declare)
+            return [] unless declare
+
+            declare.attributes.reject(&:reference?).map { |attribute| attribute.name.to_s }
+          end
+
+          # list attribute -> the command that appends to it, and how its arguments map.
+          def appends_in(commands)
+            commands.each_with_object({}) do |command, found|
+              Array(command.mutations).each do |mutation|
+                next unless mutation.op == :append
+
+                # First wins, not last: Aggregate.Attribute and Aggregate.Reference
+                # both extend `attributes`; overwriting would displace one silently.
+                found[mutation.target.to_s] ||= Append.new(verb: command.hecks_name, map: mutation.source)
+              end
+            end
+          end
+
+          # The appenders displaced by first-wins in `appends_in`; still verbs
+          # the coverage gate must see.
+          def alternates_in(commands)
+            claimed = Set.new
+            commands.flat_map do |command|
+              Array(command.mutations).filter_map do |mutation|
+                next unless mutation.op == :append
+
+                Append.new(verb: command.hecks_name, map: mutation.source) unless claimed.add?(mutation.target.to_s)
+              end
+            end
+          end
+
+          # Commands that set rather than append. Lifecycle sets two targets at once,
+          # so a setter is keyed by its verb and carries every target it writes.
+          def setters_in(commands)
+            commands.filter_map do |command|
+              targets = Array(command.mutations)
+                        .select { |mutation| mutation.op == :set }
+                        .to_h { |mutation| [mutation.target.to_s, mutation.source.to_s] }
+              next if targets.empty?
+
+              Setter.new(verb: command.hecks_name, targets: targets)
+            end
+          end
+
+          # Commands that change nothing — they exist only to be refused.
+          def sealers_in(commands)
+            commands.select { |command| Array(command.mutations).empty? }.map(&:hecks_name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,45 +1,13 @@
+require_relative "plan/category"
+require_relative "plan/verbs"
+
 module Hecks
   module Bluebook
     module MetaValidator
       # The language's own self-description, read back as a walkable structure:
       # which command appends to which list, and how the containment tree nests.
       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
+        include Verbs
 
         # Reads the language's own self-description off `registry`.
         #
@@ -126,116 +94,64 @@ module Hecks
         def read(aggregate, owner: nil, entity_owned: false)
           # entity_owned skips declaration_command: an entity's own commands
           # never carry `reference_to`, so it would misidentify one as creating.
-          declare    = entity_owned ? nil : declaration_command(aggregate)
-          parent     = parent_relationship_of(aggregate)
-          parent_key = owner ? "aggregate" : parent&.name&.to_s
-          rest       = aggregate.commands - [declare].compact
+          declare = entity_owned ? nil : declaration_command(aggregate)
+          rest    = aggregate.commands - [declare].compact
+
+          Category.new(**placement(aggregate, declare, owner), **verbs_in(aggregate, declare, rest),
+                       entity_owned: entity_owned)
+        end
+
+        # Where the category sits in the containment tree and how it is identified.
+        def placement(aggregate, declare, owner)
+          parent = parent_relationship_of(aggregate)
 
-          Category.new(
+          {
             name:           aggregate.hecks_name,
             declare:        declare&.hecks_name,
             parent:         owner || parent&.type&.target_name,
-            parent_key:     parent_key,
-            fields:         declared_fields(declare),
-            appends:        appends_in(rest),
-            alternates:     alternates_in(rest),
-            setters:        setters_in(rest),
-            sealers:        sealers_in(rest),
-            # Every command, not `rest` — the creating command carries the parent
-            # link, which is the most common reference of all.
-            references:     references_in(aggregate.commands),
+            parent_key:     owner ? "aggregate" : parent&.name&.to_s,
             # Read from the language, not restated: a hand-written join here
             # could disagree with the runtime's own by even one separator.
-            identity_paths: aggregate.identity_paths,
-            entity_owned:   entity_owned
-          )
+            identity_paths: aggregate.identity_paths
+          }
         end
 
-        # Which arguments of which verbs carry an ID, read straight off the IR.
-        def references_in(commands)
-          commands.each_with_object({}) do |command, found|
-            named = command.attributes.select(&:reference?).map { |attribute| attribute.name.to_s }
-            found[command.hecks_name] = named unless named.empty?
-          end
+        # The commands the category declares, sorted by what they do to it.
+        def verbs_in(aggregate, declare, rest)
+          {
+            fields:     declared_fields(declare),
+            appends:    appends_in(rest),
+            alternates: alternates_in(rest),
+            setters:    setters_in(rest),
+            sealers:    sealers_in(rest),
+            # Every command, not `rest` — the creating command carries the parent
+            # link, which is the most common reference of all.
+            references: references_in(aggregate.commands)
+          }
         end
 
         # `owner_id` is excluded: it's traversal context, not stored identity state.
         def declaration_command(aggregate)
           required = aggregate.identity_heads.map(&:to_sym) - [:owner_id]
-          candidates = aggregate.commands.select do |command|
-            targets = Array(command.mutations).map { |mutation| mutation.target.to_sym }
-            required.all? { |field| targets.include?(field) }
-          end
+          candidates = aggregate.commands.select { |command| establishes?(command, required) }
 
           return candidates.first if candidates.one?
 
           raise DSL::Malformed,
                 "#{aggregate.hecks_name} must declare exactly one command that establishes " \
-                "its identity fields #{required.join(', ')} — found #{candidates.map(&:hecks_name).join(', ')}"
+                "its identity fields #{required.join(", ")} — found #{candidates.map(&:hecks_name).join(", ")}"
+        end
+
+        # Whether `command` writes every one of the `fields`.
+        def establishes?(command, fields)
+          targets = Array(command.mutations).map { |mutation| mutation.target.to_sym }
+          fields.all? { |field| targets.include?(field) }
         end
 
         # The first declared reference attribute is the traversal parent.
         def parent_relationship_of(aggregate)
           aggregate.attributes.find(&:reference?)
         end
-
-        # Every reference argument is dropped, not just the parent link:
-        # a reference is not a field.
-        def declared_fields(declare)
-          return [] unless declare
-
-          declare.attributes.reject(&:reference?).map { |attribute| attribute.name.to_s }
-        end
-
-        # list attribute -> the command that appends to it, and how its arguments map.
-        def appends_in(commands)
-          commands.each_with_object({}) do |command, found|
-            Array(command.mutations).each do |mutation|
-              next unless mutation.op == :append
-
-              # First wins, not last: Aggregate.Attribute and Aggregate.Reference
-              # both extend `attributes`; overwriting would displace one silently.
-              found[mutation.target.to_s] ||= Append.new(verb: command.hecks_name, map: mutation.source)
-            end
-          end
-        end
-
-        # The appenders displaced by first-wins in `appends_in`; still verbs
-        # the coverage gate must see.
-        def alternates_in(commands)
-          claimed = {}
-          commands.flat_map do |command|
-            Array(command.mutations).filter_map do |mutation|
-              next unless mutation.op == :append
-
-              target = mutation.target.to_s
-              if claimed[target]
-                Append.new(verb: command.hecks_name, map: mutation.source)
-              else
-                claimed[target] = true
-                nil
-              end
-            end
-          end
-        end
-
-        # Commands that set rather than append. Lifecycle sets two targets at once,
-        # so a setter is keyed by its verb and carries every target it writes.
-        def setters_in(commands)
-          commands.filter_map do |command|
-            targets = Array(command.mutations)
-                      .select { |mutation| mutation.op == :set }
-                      .to_h { |mutation| [mutation.target.to_s, mutation.source.to_s] }
-            next if targets.empty?
-
-            Setter.new(verb: command.hecks_name, targets: targets)
-          end
-        end
-
-        # Commands that change nothing — they exist only to be refused.
-        def sealers_in(commands)
-          commands.select { |command| Array(command.mutations).empty? }.map(&:hecks_name)
-        end
       end
     end
   end

data/lib/hecks/bluebook/meta_validator/readings/fields.rb

@@ -0,0 +1,100 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      module Readings
+        # Reads single fields off a node: a Declare payload field, a setter's source, the
+        # target a reference points at, and the literal encoding a default rides in.
+        module Fields
+          def declared_name(node) = node.hecks_name
+
+          # Reads one Declare payload field off `node`, using
+          # Assembly::Contracts to find fields whose location differs from
+          # their name rather than branching per category.
+          def field_value(category, node, field, parent_id)
+            return declared_name(node) if field == :name
+
+            contract = Assembly.contract(category)
+            # A setter names its target as a string; Declare fields arrive as
+            # symbols, so the lookup key is normalized to a symbol either way.
+            named    = field.to_sym
+            return parent_id if contract.kind_of(named) == :parent
+
+            object, member = contract.folded(named)
+            return through(node, object, member) if member
+
+            plain_field(category, node, field)
+          end
+
+          # The fields that read straight off the node, apart from the two the contract folds.
+          def plain_field(category, node, field)
+            # `limit` is an IR object, not a scalar, so its value is unwrapped.
+            return node.limit&.to_h&.fetch(:value, nil) if "#{category}.#{field}" == "Query.limit"
+
+            # Encoded so the hash literal doesn't get spelled through Ruby's
+            # own to_s, which is not stable across Ruby versions.
+            return encode_literal(node.provenance) if field == :provenance
+
+            node.respond_to?(field) ? node.public_send(field) : nil
+          end
+
+          # Reads via `to_h` because the member names are the ones the IR
+          # spells (a Lifecycle's `default`, an OrderBy's `direction`).
+          def through(node, object, member)
+            held = node.respond_to?(object) ? node.public_send(object) : nil
+            return nil unless held
+
+            member == :transitions ? held : held.to_h[member]
+          end
+
+          def setter_value(category, node, target)
+            # `rows` folds into `closed_set` and `members` with no single
+            # member to name, so it keeps its own reader.
+            return closed_set_size(node) if "#{category}.#{target}" == "ValueObject.rows"
+
+            object, member = Assembly.contract(category).folded(target.to_sym)
+            return through(node, object, member) if member
+
+            node.respond_to?(target) ? node.public_send(target) : nil
+          end
+
+          # `nil` for "not a closed set" keeps that distinct from an empty one.
+          def closed_set_size(node)
+            return nil unless node.respond_to?(:closed_set?) && node.closed_set?
+
+            Array(node.members).size
+          end
+
+          # `Reference<Customer>` is an IR encoding; the language is offered
+          # the target head's own id instead, and resolution does the rest.
+          def points_at(row, aggregate_id)
+            return nil unless row.reference?
+
+            # Built the same way an aggregate id itself is built (chapter +
+            # name), because `repository.find` resolves against that same id.
+            Naming.identity([aggregate_id.split(Naming::IDENTITY_JOIN).first, row.type.target_name])
+          end
+
+          # Self-describing so the type survives the round trip (bare `to_s`
+          # can't tell 0.0 from a string); `nil` stays `nil`, a real answer.
+          def encode_literal(value) = value.nil? ? nil : Literal.render(value)
+
+          # The inverse of `points_at`: strips the id's chapter prefix, joined
+          # with `Naming::IDENTITY_JOIN` rather than the wire format's `::`.
+          def reference_type(points_at_id) = "Reference<#{points_at_id.to_s.split(Naming::IDENTITY_JOIN).last}>"
+
+          def row_value(row, field)
+            # Hash responds to `key` and `value` too, so a Hash must be
+            # checked for before respond_to?, not after.
+            return row[field] if row.is_a?(Hash)
+            return row.public_send(field) if row.respond_to?(field)
+            # A Struct raises for a member it lacks, so it's read via to_h
+            # instead — an absent field simply reads as absent.
+            return row.to_h[field] if row.respond_to?(:to_h) && !row.is_a?(String)
+
+            row
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,9 +1,13 @@
+require_relative "readings/fields"
+
 module Hecks
   module Bluebook
     module MetaValidator
       # Reads the parts of a bluebook IR whose shape differs from the
       # language's own, for the meta validator's walk.
       module Readings
+        include Fields
+
         # Looks up a per-category shaper (Assembly::Contracts) instead of
         # switching on category here; a list with no shaper reads straight
         # off the node.
@@ -95,7 +99,7 @@ module Hecks
         def mutation_rows(node)
           Array(node.mutations).flat_map do |mutation|
             # delegate/corrects ride the same multi-binding shape append does.
-            next set_row(mutation) unless [:append, :delegate, :corrects].include?(mutation.op)
+            next scalar_mutation_row(mutation) unless [:append, :delegate, :corrects].include?(mutation.op)
 
             mutation.source.map do |field, argument|
               # Spelled as Mutation#appended_fields spells it; Assembly::Marks
@@ -107,7 +111,7 @@ module Hecks
           end
         end
 
-        def set_row(mutation)
+        def scalar_mutation_row(mutation)
           classified = mutation.to_h[:source] || {}
 
           [{ target: mutation.target, op: mutation.op, field: mutation.target,
@@ -115,109 +119,20 @@ module Hecks
              source: classified[:name] || encode_literal(classified[:value]) }]
         end
 
+        # The columns of one canonical-form table entry, as the language declares them.
+        NORMALISATION_COLUMNS = [:strategy, :source_token, :replacement, :boundary, :position].freeze
+
         # The table belongs to the expression grammar, not to any one
         # bluebook.
         def normalisation_rows
           table = Expression::CanonicalForm.table
           return [] unless table
 
-          table.map do |entry|
-            {
-              strategy:     entry[:strategy],
-              source_token: entry[:source_token],
-              replacement:  entry[:replacement],
-              boundary:     entry[:boundary],
-              position:     entry[:position]
-            }
-          end
+          table.map { |entry| NORMALISATION_COLUMNS.to_h { |column| [column, entry[column]] } }
         rescue StandardError
           # A bluebook that cannot produce this table is not malformed.
           []
         end
-
-        def declared_name(node) = node.hecks_name
-
-        # Reads one Declare payload field off `node`, using
-        # Assembly::Contracts to find fields whose location differs from
-        # their name rather than branching per category.
-        def field_value(category, node, field, parent_id)
-          return declared_name(node) if field == :name
-
-          contract = Assembly.contract(category)
-          # A setter names its target as a string; Declare fields arrive as
-          # symbols, so the lookup key is normalized to a symbol either way.
-          named    = field.to_sym
-          return parent_id if contract.kind_of(named) == :parent
-
-          object, member = contract.folded(named)
-          return through(node, object, member) if member
-
-          # `limit` is an IR object, not a scalar, so its value is unwrapped.
-          return node.limit&.to_h&.fetch(:value, nil) if "#{category}.#{field}" == "Query.limit"
-
-          # Encoded so the hash literal doesn't get spelled through Ruby's
-          # own to_s, which is not stable across Ruby versions.
-          return encode_literal(node.provenance) if field == :provenance
-
-          node.respond_to?(field) ? node.public_send(field) : nil
-        end
-
-        # Reads via `to_h` because the member names are the ones the IR
-        # spells (a Lifecycle's `default`, an OrderBy's `direction`).
-        def through(node, object, member)
-          held = node.respond_to?(object) ? node.public_send(object) : nil
-          return nil unless held
-
-          member == :transitions ? held : held.to_h[member]
-        end
-
-        def setter_value(category, node, target)
-          # `rows` folds into `closed_set` and `members` with no single
-          # member to name, so it keeps its own reader.
-          return closed_set_size(node) if "#{category}.#{target}" == "ValueObject.rows"
-
-          object, member = Assembly.contract(category).folded(target.to_sym)
-          return through(node, object, member) if member
-
-          node.respond_to?(target) ? node.public_send(target) : nil
-        end
-
-        # `nil` for "not a closed set" keeps that distinct from an empty one.
-        def closed_set_size(node)
-          return nil unless node.respond_to?(:closed_set?) && node.closed_set?
-
-          Array(node.members).size
-        end
-
-        # `Reference<Customer>` is an IR encoding; the language is offered
-        # the target head's own id instead, and resolution does the rest.
-        def points_at(row, aggregate_id)
-          return nil unless row.reference?
-
-          # Built the same way an aggregate id itself is built (chapter +
-          # name), because `repository.find` resolves against that same id.
-          Naming.identity([aggregate_id.split(Naming::IDENTITY_JOIN).first, row.type.target_name])
-        end
-
-        # Self-describing so the type survives the round trip (bare `to_s`
-        # can't tell 0.0 from a string); `nil` stays `nil`, a real answer.
-        def encode_literal(value) = value.nil? ? nil : Literal.render(value)
-
-        # The inverse of `points_at`: strips the id's chapter prefix, joined
-        # with `Naming::IDENTITY_JOIN` rather than the wire format's `::`.
-        def reference_type(points_at_id) = "Reference<#{points_at_id.to_s.split(Naming::IDENTITY_JOIN).last}>"
-
-        def row_value(row, field)
-          # Hash responds to `key` and `value` too, so a Hash must be
-          # checked for before respond_to?, not after.
-          return row[field] if row.is_a?(Hash)
-          return row.public_send(field) if row.respond_to?(field)
-          # A Struct raises for a member it lacks, so it's read via to_h
-          # instead — an absent field simply reads as absent.
-          return row.to_h[field] if row.respond_to?(:to_h) && !row.is_a?(String)
-
-          row
-        end
       end
     end
   end

data/lib/hecks/bluebook/meta_validator/reconstruction/heads.rb

@@ -0,0 +1,89 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      class Reconstruction
+        # Rebuilds the heads of a chapter: an aggregate, its value objects and the entities
+        # nested under it, each with its own commands and asks.
+        module Heads
+          private
+
+          def aggregate(row)
+            id = row[:id]
+
+            aggregate_fields(row, id).merge(
+              value_objects: declared("ValueObject", id).map { |shape| value_object(shape) },
+              commands:      own("Command", id).map { |verb| command(verb) },
+              entities:      direct_entities(id, id).map { |piece| entity(piece) },
+              queries:       own("Query", id).map { |ask| query(ask) }
+            )
+          end
+
+          # What an aggregate row holds on its own. Read by hand, not via `declaration()`, since
+          # `aggregate` builds its hash directly; `rule` is the same reader `command`'s own uses.
+          def aggregate_fields(row, id)
+            {
+              name:          text(row[:name]),
+              description:   text(row[:description]),
+              identified_by: identity_paths(row),
+              attributes:    Array(row[:attributes]).map { |field| attribute(field, id) }
+            }.merge(aggregate_rules(row)).merge(lifecycle: lifecycle(row), provenance: provenance(row))
+          end
+
+          # The rules and projected fields an aggregate row holds.
+          def aggregate_rules(row)
+            {
+              invariants:       rules_in(row, :invariants),
+              preconditions:    rules_in(row, :preconditions),
+              projected_fields: Array(row[:projected_fields]).map { |held| projected_field(held) }
+            }
+          end
+
+          def value_object(row) = declaration("ValueObject", row)
+
+          def command(row) = declaration("Command", row)
+
+          def query(row) = declaration("Query", row).merge(options_of(row))
+
+          # Every entity sharing one root aggregate; `owner` (not the root id) tells
+          # a direct entity apart from one nested further in.
+          def direct_entities(root_id, owner_id)
+            declared("Entity", root_id).select { |held| text(held[:owner]).to_s == owner_id.to_s }
+          end
+
+          def entity(row)
+            entity_fields(row).merge(
+              commands: within("Command", row).map { |verb| command(verb) },
+              queries:  within("Query", row).map { |ask| query(ask) },
+              entities: direct_entities(text(row[:aggregate]), row[:id]).map { |piece| entity(piece) }
+            )
+          end
+
+          def entity_fields(row)
+            {
+              name:          text(row[:name]),
+              description:   text(row[:description]),
+              identified_by: identity_paths(row),
+              attributes:    Array(row[:attributes]).map { |field| shape_field(field, text(row[:aggregate])) },
+              preconditions: rules_in(row, :preconditions),
+              invariants:    rules_in(row, :invariants),
+              lifecycle:     lifecycle(row)
+            }
+          end
+
+          # Assembled from three fields, because the IR keeps one object where the
+          # language keeps the parts.
+          def lifecycle(row)
+            field = text(row[:state_field])
+            return nil if field.to_s.empty?
+
+            {
+              field:       field,
+              default:     text(row[:state_start]),
+              transitions: Array(row[:transitions]).map { |move| transition(move) }
+            }
+          end
+        end
+      end
+    end
+  end
+end