hecks 3.4.2 → 3.6.0

data/lib/hecks/bluebook/dsl/read_model_builder/sealing.rb

@@ -0,0 +1,116 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class ReadModelBuilder
+        # The build-time refusals of a read model: every option and reduction must resolve against
+        # the many-side heads its includes declared, which are only known once the body has run.
+        module Sealing
+          private
+
+          def seal_all
+            seal_query_options
+            seal_group_by
+            seal_aggregation
+            seal_cursor
+          end
+
+          # where/order_by/limit/offset/authorize's tenant apply to the many-side collections;
+          # the reference target is a single row. Every `on:` must name a many-side include, and
+          # any untargeted option needs exactly one many-side head (ADR 0055).
+          def seal_query_options
+            many = Array(@aggregate_heads).select { |head| head[:many] }
+
+            validate_declared_targets!(many)
+            return unless untargeted_option_declared?
+            return if many.size == 1
+
+            raise Malformed,
+                  "#{@name} declares where/order_by/limit/offset but includes #{many.size} many-side " \
+                  "aggregates, not exactly one — these options apply to a single collection; " \
+                  "name which one with `on:` (e.g. `where(field: value, on: Character)`), or drop the options"
+          end
+
+          # Refuses an `on:` that does not name one of the many-side includes.
+          def validate_declared_targets!(many)
+            many_by_aggregate = many.to_h { |head| [head[:aggregate], head] }
+
+            declared_targets.compact.uniq.each do |target|
+              next if many_by_aggregate.key?(target)
+
+              raise Malformed,
+                    "#{@name}'s `on: #{target}` doesn't name one of its own many-side included " \
+                    "aggregates (it includes #{many.map { |head| head[:aggregate] }.join(", ")} as " \
+                    "many-side heads)"
+            end
+          end
+
+          def declared_targets
+            Array(@wheres).map(&:target) + [@order_by&.target, @limit&.target, @offset&.target]
+          end
+
+          # `authorize`'s `tenant:` has no `on:`, so it always counts as untargeted.
+          def untargeted_option_declared?
+            Array(@wheres).any? { |where| where.target.nil? } ||
+              [@order_by, @limit, @offset].any? { |option| option && option.target.nil? } ||
+              @authorization&.tenant
+          end
+
+          # Same rule as `seal_query_options`: `group_by` needs exactly one many-side head.
+          def seal_group_by
+            return unless @group_by&.any?
+
+            many = many_side_count
+            return if many == 1
+
+            raise Malformed,
+                  "#{@name} declares group_by but includes #{many} many-side " \
+                  "aggregates, not exactly one — group_by nests a single collection's " \
+                  "own rows; name which one by including only it"
+          end
+
+          # Every reduction (`Behaviour::ReadModel::REDUCTION_FIELDS`) needs exactly one
+          # many-side head, cannot be declared alongside another, and cannot combine with
+          # `group_by`: a read model reports one shape.
+          def seal_aggregation
+            declared = Behaviour::ReadModel::REDUCTION_FIELDS
+                       .select { |ivar, _| instance_variable_get(:"@#{ivar}") }.values
+            return if declared.empty?
+
+            refuse_mixed_shapes!(declared)
+            many = many_side_count
+            return if many == 1
+
+            raise Malformed,
+                  "#{@name} declares #{declared.first} but includes #{many} many-side " \
+                  "aggregates, not exactly one — #{declared.first} reduces a single " \
+                  "collection's own rows; name which one by including only it"
+          end
+
+          def refuse_mixed_shapes!(declared)
+            if @group_by&.any?
+              raise Malformed,
+                    "#{@name} declares #{declared.join("/")} together with group_by — a read " \
+                    "model reports one shape; choose one"
+            end
+            return unless declared.size > 1
+
+            joiner = declared.size == 2 ? "both #{declared.join(" and ")}" : declared.join(", ")
+            raise Malformed, "#{@name} declares #{joiner} — a read model reports one shape; choose one"
+          end
+
+          def many_side_count = Array(@aggregate_heads).count { |head| head[:many] }
+
+          # `cursor` is parsed but no interpreter applies it, so it is refused rather than
+          # letting an author believe cursor pagination happens.
+          def seal_cursor
+            return unless @cursor
+
+            raise Malformed,
+                  "#{@name} declares cursor, but no interpreter implements cursor " \
+                  "pagination — use limit/offset instead"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,4 +1,5 @@
 require_relative "word_gate"
+require_relative "read_model_builder/sealing"
 module Hecks
   module Bluebook
     module DSL
@@ -9,6 +10,7 @@ module Hecks
 
         include QuerySpecification::Common::DSL
         include WordGate
+        include Sealing
 
         # @param name [String] the read model's own name, as written after `read_model`
         def initialize(name)
@@ -72,12 +74,7 @@ module Hecks
           @wheres ||= []
           target = resolve_target(on)
           clauses = (positional.first || {}).merge(rest)
-          clauses.each do |field, value|
-            op, operand = split_comparator(value)
-            # Fully qualified: a bare `WhereClause` reaches `ConstShim` and resolves to the
-            # grammar domain's unrelated module.
-            @wheres << QuerySpecification::Common::WhereClause.new(field: field, op: op, value: operand, target: target)
-          end
+          clauses.each { |field, value| @wheres << where_clause(field, value, target) }
         end
 
         # Records the read model's single ordering, replacing any declared earlier.
@@ -168,20 +165,8 @@ module Hecks
           Array(@includes).each do |target, as|
             add_aggregate_head(target, as, many: target != @reference_target)
           end
-          seal_query_options
-          seal_group_by
-          seal_aggregation
-          seal_cursor
-          ReadModel.new(name: @name, description: @description, reference_name: @reference_name,
-                        reference_target: @reference_target, aggregate_heads: @aggregate_heads || [],
-                        wheres: @wheres || [], order_by: @order_by, limit: @limit, offset: @offset,
-                        cursor: @cursor,
-                        authorization: @authorization, null_semantics: @null_semantics,
-                        inspection: @inspection, group_by: @group_by || [],
-                        count: @count, median_field: @median_field,
-                        sum_field: @sum_field, avg_field: @avg_field, min_field: @min_field,
-                        max_field: @max_field, percentile_field: @percentile_field,
-                        percentile_at: @percentile_at, any_field: @any_field, all_field: @all_field)
+          seal_all
+          ReadModel.new(**projection_fields, **filtering_fields, **reduction_fields)
         end
 
         # Evaluates a `read_model` block against a fresh builder and returns what it built.
@@ -198,94 +183,32 @@ module Hecks
 
         private
 
-        # where/order_by/limit/offset/authorize's tenant apply to the many-side collections;
-        # the reference target is a single row. Every `on:` must name a many-side include, and
-        # any untargeted option needs exactly one many-side head (ADR 0055).
-        def seal_query_options
-          many = Array(@aggregate_heads).select { |head| head[:many] }
-
-          validate_declared_targets!(many)
-          return unless untargeted_option_declared?
-          return if many.size == 1
-
-          raise Malformed,
-                "#{@name} declares where/order_by/limit/offset but includes #{many.size} many-side " \
-                "aggregates, not exactly one — these options apply to a single collection; " \
-                "name which one with `on:` (e.g. `where(field: value, on: Character)`), or drop the options"
-        end
-
-        # Refuses an `on:` that does not name one of the many-side includes.
-        def validate_declared_targets!(many)
-          many_by_aggregate = many.to_h { |head| [head[:aggregate], head] }
-          declared_targets = Array(@wheres).map(&:target) + [@order_by&.target, @limit&.target, @offset&.target]
-
-          declared_targets.compact.uniq.each do |target|
-            next if many_by_aggregate.key?(target)
-
-            raise Malformed,
-                  "#{@name}'s `on: #{target}` doesn't name one of its own many-side included " \
-                  "aggregates (it includes #{many.map { |head| head[:aggregate] }.join(', ')} as " \
-                  "many-side heads)"
-          end
-        end
-
-        # `authorize`'s `tenant:` has no `on:`, so it always counts as untargeted.
-        def untargeted_option_declared?
-          Array(@wheres).any? { |where| where.target.nil? } ||
-            (@order_by && @order_by.target.nil?) ||
-            (@limit && @limit.target.nil?) ||
-            (@offset && @offset.target.nil?) ||
-            @authorization&.tenant
+        # The read model's name, reference and the heads it projects.
+        def projection_fields
+          { name: @name, description: @description, reference_name: @reference_name,
+            reference_target: @reference_target, aggregate_heads: @aggregate_heads || [] }
         end
 
-        # Same rule as `seal_query_options`: `group_by` needs exactly one many-side head.
-        def seal_group_by
-          return unless @group_by&.any?
-
-          many = Array(@aggregate_heads).count { |head| head[:many] }
-          return if many == 1
-
-          raise Malformed,
-                "#{@name} declares group_by but includes #{many} many-side " \
-                "aggregates, not exactly one — group_by nests a single collection's " \
-                "own rows; name which one by including only it"
+        # The clauses, ordering and paging that narrow what the read model returns.
+        def filtering_fields
+          { wheres: @wheres || [], order_by: @order_by, limit: @limit, offset: @offset, cursor: @cursor,
+            authorization: @authorization, null_semantics: @null_semantics,
+            inspection: @inspection, group_by: @group_by || [] }
         end
 
-        # Every reduction (`Behaviour::ReadModel::REDUCTION_FIELDS`) needs exactly one
-        # many-side head, cannot be declared alongside another, and cannot combine with
-        # `group_by`: a read model reports one shape.
-        def seal_aggregation
-          declared = Behaviour::ReadModel::REDUCTION_FIELDS
-                     .select { |ivar, _| instance_variable_get(:"@#{ivar}") }.values
-          return if declared.empty?
-
-          if @group_by&.any?
-            raise Malformed,
-                  "#{@name} declares #{declared.join('/')} together with group_by — a read " \
-                  "model reports one shape; choose one"
-          end
-          if declared.size > 1
-            joiner = declared.size == 2 ? "both #{declared.join(' and ')}" : declared.join(", ")
-            raise Malformed, "#{@name} declares #{joiner} — a read model reports one shape; choose one"
-          end
-
-          many = Array(@aggregate_heads).count { |head| head[:many] }
-          return if many == 1
-
-          raise Malformed,
-                "#{@name} declares #{declared.first} but includes #{many} many-side " \
-                "aggregates, not exactly one — #{declared.first} reduces a single " \
-                "collection's own rows; name which one by including only it"
+        # The one reduction, if any, the read model reports in place of rows.
+        def reduction_fields
+          { count: @count, median_field: @median_field,
+            sum_field: @sum_field, avg_field: @avg_field, min_field: @min_field,
+            max_field: @max_field, percentile_field: @percentile_field,
+            percentile_at: @percentile_at, any_field: @any_field, all_field: @all_field }
         end
 
-        # `cursor` is parsed but no interpreter applies it, so it is refused rather than
-        # letting an author believe cursor pagination happens.
-        def seal_cursor
-          return unless @cursor
-
-          raise Malformed,
-                "#{@name} declares cursor, but no interpreter implements cursor " \
-                "pagination — use limit/offset instead"
+        # Fully qualified: a bare `WhereClause` reaches `ConstShim` and resolves to the
+        # grammar domain's unrelated module.
+        def where_clause(field, value, target)
+          op, operand = split_comparator(value)
+          QuerySpecification::Common::WhereClause.new(field: field, op: op, value: operand, target: target)
         end
 
         # Resolves `on:` to a type name; `nil` when omitted.

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

@@ -13,7 +13,15 @@ module Hecks
         #
         # extraction_failure is required, not hardcoded, since given/invariant/ensures
         # each need their own exact refusal wording.
-        def build_rule(struct_class, description, predicate, owner_name:, word:, extraction_failure:)
+        #
+        # @param struct_class [Class] the rule struct to build (Given or Invariant)
+        # @param description [String] the rule's description
+        # @param predicate [Proc] the rule's predicate block
+        # @param context [Hash] `owner_name:`, `word:` and `extraction_failure:`, all required
+        # @return [Object] an instance of `struct_class`
+        # @raise [Bluebook::DSL::Malformed] if the predicate's source could not be read
+        def build_rule(struct_class, description, predicate, **context)
+          owner_name, word, extraction_failure = context.fetch_values(:owner_name, :word, :extraction_failure)
           canonical = Ports::Extraction.canonical(predicate)
 
           if canonical.to_s.empty?
@@ -22,11 +30,16 @@ module Hecks
                   "extraction — #{extraction_failure}"
           end
 
-          rule_word = "#{word} #{description.inspect}"
+          ast = checked_ast(canonical, owner_name, "#{word} #{description.inspect}")
+          struct_class.new(description: description, canonical: canonical, predicate: predicate, ast: ast)
+        end
+
+        # Emits a predicate's AST and refuses the patterns and lookups the IR cannot share.
+        def checked_ast(canonical, owner_name, rule_word)
           ast = Expression::AstJson.emit_predicate(canonical)
           Expression::AstJson.refuse_unshared_patterns!(ast, owner: owner_name, word: rule_word)
           Expression::AstJson.refuse_unresolvable_lookups!(ast, owner: owner_name, word: rule_word)
-          struct_class.new(description: description, canonical: canonical, predicate: predicate, ast: ast)
+          ast
         end
 
         # Resolution primitive 1: first pool (in order) whose hash has this description wins.
@@ -61,16 +74,17 @@ module Hecks
         # Reads how a (word, context) pair resolves rule references, off the self-hosted
         # grammar table (or, during bootstrap, the projected fallback).
         def lookup(word, context)
-          if MetaValidator.bootstrapping?
-            BOOTSTRAP_FALLBACK[[word, context]] || {}
-          else
-            row = MetaValidator::SyntaxBoot.call[:keywords]
-                                           .find { |r| r[:word] == word && r[:context] == context }
-            return {} unless row
+          return BOOTSTRAP_FALLBACK[[word, context]] || {} if MetaValidator.bootstrapping?
 
-            { resolves_via: row[:resolves_via], disambiguator: row[:disambiguator] }
-              .transform_values { |value| value.to_s.empty? ? nil : value }
-          end
+          row = MetaValidator::SyntaxBoot.call[:keywords]
+                                         .find { |r| r[:word] == word && r[:context] == context }
+          row ? resolution_of(row) : {}
+        end
+
+        # The primitive and disambiguator a grammar-table row names, blank values as nil.
+        def resolution_of(row)
+          { resolves_via: row[:resolves_via], disambiguator: row[:disambiguator] }
+            .transform_values { |value| value.to_s.empty? ? nil : value }
         end
 
         # Raises if syntax.bluebook's own resolves_via for (word, context) disagrees with

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

@@ -15,16 +15,9 @@ module Hecks
         def initialize(name, was: nil)
           raise Malformed, "an aggregate translation needs a name" if name.to_s.empty?
 
-          @name      = name
-          @was       = was
-          @renames   = {}
-          @moves     = []
-          @converts  = []
-          @drops     = []
-          @retypes   = []
-          @computes  = []
-          @rekeys    = []
-          @backfills = []
+          @name = name
+          @was  = was
+          start_rule_lists
         end
 
         # Declares a field rename with no other change: same path, new name.
@@ -172,6 +165,17 @@ module Hecks
 
         private
 
+        def start_rule_lists
+          @renames   = {}
+          @moves     = []
+          @converts  = []
+          @drops     = []
+          @retypes   = []
+          @computes  = []
+          @rekeys    = []
+          @backfills = []
+        end
+
         def unresolved_message(name, candidates)
           return identity_unresolved_message if name.to_sym == :identity
 
@@ -180,7 +184,7 @@ module Hecks
             "#{@name}'s translation leaves #{render_path(name)} unresolved (no candidate matched — " \
               "consider drop, or compute on Postgres) — replace unresolved with a real rule before booting."
           else
-            "#{@name}'s translation leaves #{render_path(name)} unresolved (candidates: #{rendered.join(', ')}) — " \
+            "#{@name}'s translation leaves #{render_path(name)} unresolved (candidates: #{rendered.join(", ")}) — " \
               "replace unresolved with a rename, move, convert, or drop before booting."
           end
         end
@@ -212,9 +216,7 @@ module Hecks
         # @param to [String, Symbol] the destination era
         # @raise [Bluebook::DSL::Malformed] if `domain`, `from`, or `to` is empty
         def initialize(domain, from:, to:)
-          raise Malformed, "a translation names no domain" if domain.to_s.empty?
-          raise Malformed, "#{domain}'s translation says nothing about its origin era (from:)" if from.to_s.empty?
-          raise Malformed, "#{domain}'s translation says nothing about its destination era (to:)" if to.to_s.empty?
+          refuse_blank_era_pair!(domain, from, to)
 
           @domain     = domain
           @from       = from
@@ -268,6 +270,14 @@ module Hecks
           builder.instance_eval(&block) if block
           builder.build
         end
+
+        private
+
+        def refuse_blank_era_pair!(domain, from, to)
+          raise Malformed, "a translation names no domain" if domain.to_s.empty?
+          raise Malformed, "#{domain}'s translation says nothing about its origin era (from:)" if from.to_s.empty?
+          raise Malformed, "#{domain}'s translation says nothing about its destination era (to:)" if to.to_s.empty?
+        end
       end
     end
   end

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

@@ -26,22 +26,11 @@ module Hecks
         # because frozen era text still writes it. Only the wrapper passes a block.
         def one_of_impl(*values, &block)
           unless block
-            # An empty one_of names a closed set with nothing in it; refuse rather than no-op.
-            if values.empty?
-              raise Malformed,
-                    "#{@name}'s one_of names no values — one_of(\"a\", \"b\") takes at least one, or " \
-                    "give the attribute its own one_of: [...] for a named closed set"
-            end
-
+            refuse_empty_one_of!(values)
             return super(*values)
           end
 
-          unless MetaValidator.shadow_parsing?
-            raise Malformed,
-                  "#{@name}'s one_of do ... end wrapper is gone — give the single attribute its " \
-                  "own one_of: [...], or write bare member lines with no wrapper for a multi-field set"
-          end
-
+          refuse_one_of_wrapper!
           @closed_set = true
           instance_eval(&block)
         end
@@ -78,12 +67,7 @@ module Hecks
         public
 
         def build
-          if @inline_closed_set_field && attributes.size > 1
-            raise Malformed,
-                  "#{@name}'s one_of: on :#{@inline_closed_set_field} only works when it is the " \
-                  "value object's only attribute — #{attributes.size} declared here; write bare " \
-                  "member lines instead for a multi-field set"
-          end
+          refuse_multi_field_inline_set!
 
           ValueObject.declare(
             name: @name, attributes: attributes,
@@ -100,6 +84,32 @@ module Hecks
 
         private
 
+        # An empty one_of names a closed set with nothing in it; refuse rather than no-op.
+        def refuse_empty_one_of!(values)
+          return unless values.empty?
+
+          raise Malformed,
+                "#{@name}'s one_of names no values — one_of(\"a\", \"b\") takes at least one, or " \
+                "give the attribute its own one_of: [...] for a named closed set"
+        end
+
+        def refuse_one_of_wrapper!
+          return if MetaValidator.shadow_parsing?
+
+          raise Malformed,
+                "#{@name}'s one_of do ... end wrapper is gone — give the single attribute its " \
+                "own one_of: [...], or write bare member lines with no wrapper for a multi-field set"
+        end
+
+        def refuse_multi_field_inline_set!
+          return unless @inline_closed_set_field && attributes.size > 1
+
+          raise Malformed,
+                "#{@name}'s one_of: on :#{@inline_closed_set_field} only works when it is the " \
+                "value object's only attribute — #{attributes.size} declared here; write bare " \
+                "member lines instead for a multi-field set"
+        end
+
         # Private callback `attribute` invokes for `one_of:`. A single-field set names exactly one
         # field; a second one would leave it ambiguous which field each member line belongs to.
         def install_inline_closed_set(field, values)

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

@@ -19,13 +19,8 @@ module Hecks
 
         def method_missing(word, *args, **kwargs, &block)
           if MetaValidator.bootstrapping?
-            fallback = GenericDispatch::BOOTSTRAP_CALLS_FALLBACK
-            # Own context first, then "Type", as in `word_gate_dispatch`.
-            own_key  = [self.class::GRAMMAR_CONTEXT, word.to_s]
-            type_key = ["Type", word.to_s]
-            found  = fallback.key?(own_key) || fallback.key?(type_key)
-            target = fallback.key?(own_key) ? fallback[own_key] : fallback[type_key]
-            return send(target, *args, **kwargs, &block) if found
+            key = word_gate_bootstrap_key(word)
+            return send(GenericDispatch::BOOTSTRAP_CALLS_FALLBACK[key], *args, **kwargs, &block) if key
 
             return super
           end
@@ -36,33 +31,45 @@ module Hecks
           result
         end
 
+        # Own context first, then "Type", as in `word_gate_dispatch`.
+        def word_gate_bootstrap_key(word)
+          fallback = GenericDispatch::BOOTSTRAP_CALLS_FALLBACK
+          [[self.class::GRAMMAR_CONTEXT, word.to_s], ["Type", word.to_s]].find { |key| fallback.key?(key) }
+        end
+
+        # `one_of`/`list_of` in an attribute's type position run on whichever builder is
+        # evaluating, whose context is never "Type". Try "Type" only when its own context has
+        # no row, so a same-named row of its own (ValueObject's `one_of`) still wins.
+        #
+        # Returns the context the word was admitted under and the rows admitting it.
+        def word_gate_admitted(keywords, context, word)
+          admitted = keywords.select { |row| word_gate_row?(row, context, word.to_s) }
+          return [context, admitted] unless admitted.empty?
+
+          type_admitted = keywords.select { |row| row[:context] == "Type" && row[:word] == word.to_s }
+          type_admitted.empty? ? [context, admitted] : ["Type", type_admitted]
+        end
+
+        def word_gate_row?(row, context, name)
+          row[:context] == context && (row[:word] == name || row[:was] == name)
+        end
+
+        def refuse_unadmitted_word!(keywords, context, word)
+          legal = keywords.select { |row| row[:context] == context }.map { |row| row[:word] }.uniq.sort
+          raise Malformed,
+                "'#{word}' is not a word #{context} admits — legal words here: #{legal.join(", ")}"
+        end
+
         # Admission then dispatch: own context, "Type" fallback, admitted-elsewhere check,
         # `GenericDispatch`. Returns `NOT_ADMITTED` for an unknown word rather than raising.
-        # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def word_gate_dispatch(word, args, kwargs, block)
-          context = self.class::GRAMMAR_CONTEXT
           rows = MetaValidator::SyntaxBoot.call
           keywords = rows[:keywords]
-          admitted = keywords.select { |row| row[:context] == context && (row[:word] == word.to_s || row[:was] == word.to_s) }
-
-          # `one_of`/`list_of` in an attribute's type position run on whichever builder is
-          # evaluating, whose context is never "Type". Try "Type" only when its own context has
-          # no row, so a same-named row of its own (ValueObject's `one_of`) still wins.
-          if admitted.empty?
-            type_admitted = keywords.select { |row| row[:context] == "Type" && row[:word] == word.to_s }
-            unless type_admitted.empty?
-              admitted = type_admitted
-              context = "Type"
-            end
-          end
+          context, admitted = word_gate_admitted(keywords, self.class::GRAMMAR_CONTEXT, word)
 
           return NOT_ADMITTED if admitted.empty? && !admitted_anywhere?(keywords, word)
 
-          if admitted.empty?
-            legal = keywords.select { |row| row[:context] == context }.map { |row| row[:word] }.uniq.sort
-            raise Malformed,
-                  "'#{word}' is not a word #{context} admits — legal words here: #{legal.join(', ')}"
-          end
+          refuse_unadmitted_word!(keywords, context, word) if admitted.empty?
 
           dispatched = GenericDispatch.try(self, context, word.to_s, args, kwargs, block, rows)
           return dispatched unless dispatched.equal?(GenericDispatch::NOT_HANDLED)
@@ -77,7 +84,7 @@ module Hecks
 
           context = self.class::GRAMMAR_CONTEXT
           keywords = MetaValidator::SyntaxBoot.call[:keywords]
-          keywords.any? { |row| row[:context] == context && (row[:word] == word.to_s || row[:was] == word.to_s) } ||
+          keywords.any? { |row| word_gate_row?(row, context, word.to_s) } ||
             keywords.any? { |row| row[:context] == "Type" && row[:word] == word.to_s } ||
             super
         end

data/lib/hecks/bluebook/entity.rb

@@ -1,4 +1,5 @@
 require_relative "behaviour/entity"
+require_relative "keyword_fields"
 require_relative "expression/ast_json"
 
 module Hecks
@@ -29,6 +30,12 @@ module Hecks
         lifecycle:     one(:lifecycle)
       )
 
+      # Every optional declared field and what it holds when the declaration omits it.
+      FIELD_DEFAULTS = {
+        description: nil, identified_by: nil, attributes: [], commands: [], queries: [],
+        entities: [], preconditions: [], invariants: [], lifecycle: nil
+      }.freeze
+
       class << self
         attr_reader :description, :identified_by, :identity_paths, :identity_heads,
                     :attributes, :commands, :queries, :entities, :preconditions, :invariants, :lifecycle
@@ -42,31 +49,20 @@ module Hecks
         # @param entities [Array<Class>] the entity classes nested directly under this entity
         # @param lifecycle [Bluebook::Lifecycle, nil] the declared state machine, or `nil`
         # @return [Class] the minted piece class (a `Bluebook::Entity` subclass)
-        def declare(name:, description: nil, identified_by: nil, attributes: [],
-                    commands: [], queries: [], entities: [], preconditions: [], invariants: [], lifecycle: nil)
+        def declare(name:, **given)
           piece = Class.new(self)
           piece.hecks_name = name.to_s
-          piece.absorb(description: description, identified_by: identified_by,
-                       attributes: attributes, commands: commands,
-                       queries: queries, entities: entities, preconditions: preconditions,
-                       invariants: invariants, lifecycle: lifecycle)
+          piece.absorb(**KeywordFields.fill(given, FIELD_DEFAULTS))
           piece.stamp_children
           piece
         end
 
         # Assigns the declared fields, then lets the behaviour's `settle` derive identity and
         # indexes.
-        def absorb(description:, identified_by:, attributes:, commands:, queries:, entities:, preconditions:, invariants:,
-                   lifecycle:)
-          @description    = description
-          @identified_by  = identified_by
-          @attributes     = attributes
-          @commands       = commands
-          @queries        = queries
-          @entities       = entities
-          @preconditions  = preconditions
-          @invariants     = invariants
-          @lifecycle      = lifecycle
+        def absorb(**fields)
+          KeywordFields.fill(fields, FIELD_DEFAULTS).each do |key, value|
+            instance_variable_set(:"@#{key}", value)
+          end
 
           settle
         end