hecks 1.3.0 → 1.5.0

data/lib/hecks/runtime/value/admission.rb

@@ -8,6 +8,15 @@ module Hecks
       # refusals that make them rules rather than decoration. Extended into
       # Value beside Coercion; `self` is the Value class.
       module Admission
+        # Refuses fields that match no declared member of a closed-set (`one_of`) value object.
+        #
+        # @param value_object [Bluebook::ValueObject] the type being built; one with no
+        #   members is not a closed set and is never refused
+        # @param fields [Hash{Symbol => Object}] the offered fields, keyed by attribute name
+        # @return [nil] when the type has no members, or some member matches on every
+        #   field it names
+        # @raise [Runtime::InvariantViolation] if no member matches; the message lists the
+        #   admitted values of the first attribute and the one offered
         def admit_member(value_object, fields)
           return if value_object.members.empty?
 
@@ -17,42 +26,54 @@ module Hecks
           return if value_object.members.any? { |member| member_matches?(member, fields) }
 
           raise InvariantViolation,
-                RefusalWording.render("InvariantViolation", "closed_set_member",
-                                      type: value_object.hecks_name,
-                                      admitted: admitted.map(&:inspect).join(", "), offered: offered.inspect)
+                RefusalWording.render_site("InvariantViolation", "closed_set_member",
+                                           type: value_object.hecks_name,
+                                           admitted: admitted, offered: offered.inspect)
         end
 
-        # EVERY DECLARED FIELD, not only the discriminant — a multi-column
+        # Every declared field, not only the discriminant — a multi-column
         # `member` row (`StatementFrequency`'s `cadence`/`retention_months`/
         # `paper_fee_cents`, statements.bluebook) names a whole tuple, and a
         # caller offering the right `cadence` with the wrong
-        # `retention_months` is not a genuine member just because the FIRST
-        # column happened to match. `admitted.include?(offered.to_s)` above
-        # used to be the entire check, so it stopped at that first column —
+        # `retention_months` is not a genuine member just because the first
+        # column happened to match. Comparing only the discriminant
+        # (`admitted.include?(offered.to_s)`) stops at that first column —
         # confirmed live: `Value.build(StatementFrequency, cadence:
-        # "monthly", retention_months: 999, paper_fee_cents: 999)` was
-        # admitted outright, no member of the closed set declares that row.
+        # "monthly", retention_months: 999, paper_fee_cents: 999)` would be
+        # admitted outright, though no member of the closed set declares that row.
         # A single-field set (`AccountKind`, `LedgerDirection`, ...) has
-        # exactly one key here, so this reduces to the original discriminant-
-        # only comparison for every set that only ever had one column to
-        # begin with — same refusal, same wording, unchanged.
+        # exactly one key here, so this reduces to a discriminant-only
+        # comparison for every set that has one column — same refusal,
+        # same wording.
         private def member_matches?(member, fields)
           member.all? { |field, value| fields[field].to_s == value.to_s }
         end
 
-        # THE SAME REFUSAL, FOR A SET NAMED SOMEWHERE ELSE.
+        # Checks a value against the closed set its attribute names with `admits:`.
+        #
+        # The same refusal, for a set named somewhere else.
         #
-        # `admit_member` above refuses a non-member when the value object BEING
-        # BUILT is itself the closed set — which is the only shape `one_of` can
-        # make, because it SYNTHESISES the set from the values written inline. An
+        # `admit_member` above refuses a non-member when the value object being
+        # built is itself the closed set — which is the only shape `one_of` can
+        # make, because it synthesises the set from the values written inline. An
         # `admits:` attribute is the other direction: the value is an ordinary
         # String or a plain text holder, and the set it must belong to was
         # declared once, elsewhere, and is named rather than restated.
         #
-        # Without this the word was a DECLARATION and nothing more — read by
+        # Without this the word was a declaration and nothing more — read by
         # projections, read by nobody at the door. A rule
         # that cannot be the one to refuse is decoration, and this language has
         # paid for that mistake before.
+        #
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity, Bluebook::ValueObject] the
+        #   construct that declares `attribute`; the walk to the chapter starts here
+        # @param attribute [Bluebook::Attribute, nil] the attribute being filled; nil, or one
+        #   with no `admits:`, means nothing is checked
+        # @param value [Object, nil] the coerced value: a bare scalar, or a `Runtime::Value`
+        #   holding one field; nil is never checked
+        # @return [Object, nil] `value`, unchanged
+        # @raise [Runtime::InvariantViolation] if the value is not a member of the named set,
+        #   or `admits:` names a set no aggregate in the chapter declares
         def admit_declared_set(owner, attribute, value)
           return value if attribute.nil? || attribute.admits.nil? || value.nil?
 
@@ -61,21 +82,32 @@ module Hecks
           return value if admitted.include?(offered.to_s)
 
           raise InvariantViolation,
-                RefusalWording.render("InvariantViolation", "admits_declared_set",
-                                      name: attribute.name, admits: attribute.admits,
-                                      admitted: admitted.map(&:inspect).join(", "), offered: offered.inspect)
+                RefusalWording.render_site("InvariantViolation", "admits_declared_set",
+                                           name: attribute.name, admits: attribute.admits,
+                                           admitted: admitted, offered: offered.inspect)
         end
 
-        # `Vocabulary::MutationOp` — the aggregate that HOLDS the set, then the
-        # set. Qualified because a closed set is a value object INSIDE an
+        # Lists the values the closed set named by an attribute's `admits:` allows.
+        #
+        # `Vocabulary::MutationOp` — the aggregate that holds the set, then the
+        # set. Qualified because a closed set is a value object inside an
         # aggregate, which is exactly why `admits` could not be spelled as a
         # reference: `reference_to` reaches aggregate heads and nothing below one.
         #
-        # RESOLVED LATE, like `Reference#resolve` and for the same reason — the
+        # Resolved late, like `Reference#resolve` and for the same reason — the
         # set may be declared further down the file than the attribute that names
-        # it. And REFUSED when it resolves to nothing, also like `Reference`: a
+        # it. And refused when it resolves to nothing, also like `Reference`: a
         # link checked against nothing is worse than no link, because it reads
         # like a rule.
+        #
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity, Bluebook::ValueObject] the
+        #   construct that declares `attribute`
+        # @param attribute [Bluebook::Attribute] an attribute whose `admits` is
+        #   `"Aggregate::SetName"`
+        # @return [Array<String>] each member's value for the set's first attribute, as a String,
+        #   in declaration order
+        # @raise [Runtime::InvariantViolation] if `admits` is not qualified, no chapter is
+        #   reachable from `owner`, or the chapter declares no such aggregate or value object
         def admitted_members(owner, attribute)
           aggregate_name, set_name = attribute.admits.to_s.split("::", 2)
           chapter = chapter_of(owner)
@@ -83,26 +115,39 @@ module Hecks
 
           unless set
             raise InvariantViolation,
-                  RefusalWording.render("InvariantViolation", "undeclared_set",
-                                        name: attribute.name, admits: attribute.admits)
+                  RefusalWording.render_site("InvariantViolation", "undeclared_set",
+                                             name: attribute.name, admits: attribute.admits)
           end
 
           discriminant = set.attributes.first.name
           set.members.map { |member| member.to_h[discriminant].to_s }
         end
 
-        # UP TO THE CHAPTER, from wherever the attribute was declared. A value
+        # Walks `hecks_owner` links upward until it reaches the chapter.
+        #
+        # Up to the chapter, from wherever the attribute was declared. A value
         # object's owner is its aggregate and an aggregate's owner is its chapter,
         # so the walk stops at the first construct that can answer for an
-        # aggregate BY NAME — which is the chapter, and only the chapter.
+        # aggregate by name — which is the chapter, and only the chapter.
+        #
+        # @param construct [Bluebook::ValueObject, Bluebook::Entity, Bluebook::Aggregate,
+        #   Bluebook::Chapter, nil] the construct to start from; the chapter answers itself
+        # @return [Bluebook::Chapter, nil] the first construct on the way up that responds to
+        #   `aggregate`; nil when the chain ends without one
         def chapter_of(construct)
           node = construct
           node = node.hecks_owner while node && !node.respond_to?(:aggregate) && node.respond_to?(:hecks_owner)
           node.respond_to?(:aggregate) ? node : nil
         end
 
-        # An admitted value is a SCALAR however it arrived — as a bare string on a
+        # Unwraps a one-field value object to the scalar it holds, so membership compares scalars.
+        #
+        # An admitted value is a scalar however it arrived — as a bare string on a
         # plain field, or wrapped in the one-field holder its type names.
+        #
+        # @param value [Object] a bare scalar, or a `Runtime::Value`
+        # @return [Object] the sole field's value for a one-field `Runtime::Value`; otherwise
+        #   `value` itself, a multi-field `Runtime::Value` included
         def admitted_scalar(value)
           return value unless value.is_a?(self)
 
@@ -110,7 +155,7 @@ module Hecks
           fields.size == 1 ? fields.values.first : value
         end
 
-        # A FIELD OF A VALUE OBJECT MAY NAME A SET TOO.
+        # A field of a value object may name a set too.
         #
         # Beside check_patterns and for the same reason: `Query::Filter.op` is a
         # plain String field that admits `Vocabulary::QueryComparator`, and the