hecks 2.7.0 → 2.9.0

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

@@ -2,12 +2,8 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
-      # Parses an `aggregate "Name" do ... end` block inside a `.translation`
-      # file into a `TranslationAggregate` — the per-aggregate rules
-      # (`rename`/`move`/`convert`/`retype`/`compute`/`rekey`/`backfill`/
-      # `drop`) that carry one era's stored data forward to the next, plus
-      # `unresolved` markers the scaffold writes wherever it cannot decide a
-      # rule for itself.
+      # Parses an `aggregate "Name" do ... end` block in a `.translation` file into a
+      # `TranslationAggregate`: the rules that carry one era's stored data to the next.
       class TranslationAggregateBuilder
         GRAMMAR_CONTEXT = "TranslationAggregate".freeze
 
@@ -33,17 +29,6 @@ module Hecks
 
         # Declares a field rename with no other change: same path, new name.
         #
-        # Answers the `rename` word (and, via the same table rows, its
-        # siblings `move`/`convert`/`retype`/`compute`/`rekey`/`backfill`
-        # below) through the table's `calls:` column — item #13's full
-        # metaprogrammed dispatch (slice 4c). Each is carried in
-        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK` like every other
-        # `calls:`-routed word, but none of their rows are ever consulted
-        # during real bootstrap: `translation.bluebook` describes its own
-        # structure with aggregate/entity/attribute, never with these —
-        # they're words for real, user-authored `.translation` files
-        # only, loaded after the grammar table already exists.
-        #
         # @param old_name [Symbol, String] the field's name in the held era
         # @param to [Symbol, String] the field's name in the destination era
         # @return [void]
@@ -72,12 +57,8 @@ module Hecks
         # Declares an exhaustive value-to-value mapping for a field with nothing structural in
         # common with its replacement.
         #
-        # A value with nothing structural in common with its replacement
-        # — declared as an exhaustive table, not computed, so every value
-        # that can appear in old data has a named destination. Paths
-        # follow `move`'s convention: dotted reaches a value-object member.
-        #
-        # @param old_path [String, Symbol] the field's path in the held era
+        # @param old_path [String, Symbol] the field's path in the held era; dotted reaches a
+        #   value-object member
         # @param to [String, Symbol] the field's path in the destination era
         # @param values [Hash] every old value mapped to its destination value
         # @return [Array<Bluebook::TranslationConvert>] every convert declared so far, this one
@@ -92,20 +73,13 @@ module Hecks
           @converts << TranslationConvert.new(old_path.to_s, to.to_s, values)
         end
 
-        # `drop` — item #13's full metaprogrammed dispatch, slice 2
-        # (whole-project table-unification survey): a declared,
-        # deliberate acknowledgment that an attribute's data does not
-        # survive the rename — the honest alternative to letting it
-        # vanish because nothing named it. A blank-guarded, kind-driven
-        # coerce-and-append with nothing else, now executed by
-        # `GenericDispatch`.
+        # `drop` (attribute data that does not survive the rename) is dispatched directly off
+        # the grammar table by `GenericDispatch`; no method answers it here.
 
         # Declares that a type's name changed while its member structure stayed the same.
         #
-        # A value object's or entity's own type name changed, member
-        # structure unchanged. The stored data never carries the type
-        # name, so nothing moves — this declares that the pair of names
-        # means the same shape, which is what lets the era diff accept it.
+        # Nothing moves: stored data never carries the type name, so this only tells the era
+        # diff that the two names mean the same shape.
         #
         # @param old_type [String, Symbol] the type's name in the held era
         # @param to [String, Symbol] the type's name in the destination era
@@ -121,10 +95,8 @@ module Hecks
 
         # Declares a field computed by a hand-written Postgres SQL expression.
         #
-        # A computed transform whose only implementation is the SQL
-        # expression itself — Postgres-only by construction. The scaffold
-        # never proposes one; a human writes it, and the audit's
-        # human-sampled review is its only verification.
+        # The scaffold never proposes one; a human writes it, and human-sampled review is
+        # its only verification.
         #
         # @param old_path [String, Symbol] the source field's path in the held era
         # @param to [String, Symbol] the field's path in the destination era
@@ -143,14 +115,8 @@ module Hecks
         # Declares a hand-written Postgres SQL expression that recomputes the aggregate's own
         # identity.
         #
-        # The aggregate's own identity, changing what it's computed from —
-        # not a field crossing a boundary (`move`), not a value's own
-        # transform (`compute`): the record's key. No path arguments,
-        # unlike every rule above — nothing is consumed from or moved into
-        # `state`, only what identifies the record is recomputed. Same
-        # SQL-only, Postgres-only, human-reviewed-sample-is-the-only-
-        # verification shape `compute` already has, and for the same
-        # reason: there is nothing in-process to check this against.
+        # No path arguments, unlike the rules above: only the record's key is recomputed, not
+        # state moved into it. Verified the same human-reviewed-only way as `compute`.
         #
         # @param sql [String] the Postgres SQL expression computing the destination identity
         # @return [Array<Bluebook::TranslationRekey>] every rekey declared so far, this one last
@@ -164,17 +130,8 @@ module Hecks
         # Declares a newly added, required attribute and the default existing records read
         # until a real value is written.
         #
-        # A newly added, required attribute — the addition-side sibling of
-        # `drop`. Nothing to rename, move, or convert from, since old data
-        # never held this field at all; `default` is what an existing
-        # record reads until the next command against it writes a real
-        # value. Adapter-agnostic, unlike `compute` — applied the same
-        # in-process way rename/move/drop already are
-        # (`Lineage#translate`), because there is nothing to compute here,
-        # only a value to declare. This is what
-        # `EraGuard.refuse_unsafe_addition!` asks for when a non-optional
-        # attribute with no default: could leave an existing record with
-        # the field genuinely absent.
+        # What `EraGuard.refuse_unsafe_addition!` requires before a non-optional attribute
+        # with no default can boot.
         #
         # @param name [String, Symbol] the new attribute's name
         # @param default [Object] the value an existing record reads until it is written for real
@@ -190,22 +147,6 @@ module Hecks
 
         # Always refuses to boot: marks a field the scaffold could not decide a rule for.
         #
-        # The scaffold writes this where it cannot decide; a file carrying
-        # one can only boot into this refusal — never a guess.
-        #
-        # Answers the `unresolved` word through the table's `calls:`
-        # column — item #13's full metaprogrammed
-        # dispatch (slice 4). Builds its own message with real branching
-        # (empty vs. named candidates, a special :identity case), not a
-        # fixed string a boolean `refuses:` flag could express. Carried in
-        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK` like every other
-        # `calls:`-routed word, but that row is never consulted during
-        # real bootstrap (checked directly, not assumed):
-        # translation.bluebook (loaded during bootstrap, to describe the
-        # translation DSL itself) never writes `unresolved` — that word is
-        # only ever used by real, user-authored `.translation` files,
-        # loaded well after the grammar table already exists.
-        #
         # @param name [String, Symbol] the unresolved field's name, or `:identity` for an
         #   unresolved identity change
         # @param candidates [Array<String, Symbol>] paths the scaffold considered but could not
@@ -216,14 +157,8 @@ module Hecks
           raise Malformed, unresolved_message(name, candidates)
         end
 
-        # `method_missing`/`respond_to_missing?` answer off the self-hosted
-        # grammar table (via the `include`d `WordGate`, above), giving a
-        # richer, table-driven "must be rename, move, convert, ..." refusal
-        # on a genuinely undefined call than a hand-typed list could —
-        # the exact "hardcoded legal-word list" this whole arc's item #13
-        # exists to close. A word admitted
-        # elsewhere in the grammar but not in this context still gets that
-        # richer refusal.
+        # `method_missing`/`respond_to_missing?` (via the included `WordGate`) give a
+        # table-driven refusal naming the legal words, rather than a hand-typed list.
 
         # Assembles the declared rules into a `TranslationAggregate`.
         #
@@ -265,11 +200,8 @@ module Hecks
         end
       end
 
-      # Parses a whole `.translation` file into a `Translation` — the
-      # domain's own `from:`/`to:` era pair, its list of `aggregate`
-      # translation blocks (each built by `TranslationAggregateBuilder`
-      # above), and any `retired` aggregates that no longer exist in the
-      # destination era.
+      # Parses a whole `.translation` file into a `Translation`: the domain's `from:`/`to:`
+      # era pair, its `aggregate` blocks, and any `retired` aggregates.
       class TranslationBuilder
         GRAMMAR_CONTEXT = "Translation".freeze
 
@@ -291,43 +223,25 @@ module Hecks
           @retired    = []
         end
 
-        # Declares one aggregate's own translation rules.
-        #
-        # Answers the `aggregate` word through the table's `calls:`
-        # column — item #13's full metaprogrammed
-        # dispatch (slice 4c). Not bootstrap-reachable — this "Translation"
-        # -context `aggregate` (opens a TranslationAggregateBuilder) is a
-        # different (context, word) pair than "Bluebook"-context
-        # `aggregate` (the one translation.bluebook itself is described
-        # with), so it never describes the language's own
-        # translation chapter.
+        # Declares one aggregate's own translation rules; a distinct (context, word) pair
+        # from "Bluebook"-context `aggregate`, despite sharing the word.
         #
         # @param name [String, Symbol] the aggregate's name in the destination era
         # @param was [String, Symbol, nil] the aggregate's earlier name, when renamed
-        # @yield the aggregate's own translation body, evaluated against a
-        #   `TranslationAggregateBuilder`
-        # @return [Array<Bluebook::TranslationAggregate>] every aggregate translation declared
-        #   so far, this one last
-        # @raise [Bluebook::DSL::Malformed] if `name` is empty, or any rule in the body fails
-        #   its own checks
+        # @yield the translation body, evaluated against a `TranslationAggregateBuilder`
+        # @return [Array<Bluebook::TranslationAggregate>] every declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if `name` is empty, or a body rule fails its own checks
         def aggregate_impl(name, was: nil, &block)
           builder = TranslationAggregateBuilder.new(name, was: was)
           builder.instance_eval(&block) if block
           @aggregates << builder.build
         end
 
-        # `retired` (an aggregate that is gone outright, not renamed — the
-        # deliberate alternative to a bogus `was:` claim on an unrelated
-        # aggregate, the same shape `TranslationAggregateBuilder#drop` is)
-        # is executed straight off the grammar table by `GenericDispatch` —
-        # item #13's full metaprogrammed dispatch, slice 2 (whole-project
-        # table-unification survey) — so no hand-written method answers it here.
-
-        # `method_missing`/`respond_to_missing?` answer off the self-hosted
-        # grammar table (via the `include`d `WordGate`, above, the same
-        # mechanism `TranslationAggregateBuilder`'s own comment describes
-        # one level up) instead of a hand-typed "it declares aggregate
-        # blocks and retired aggregates" message.
+        # `retired` (an aggregate gone outright, not renamed) is dispatched straight off the
+        # grammar table by `GenericDispatch`; no method answers it here.
+
+        # `method_missing`/`respond_to_missing?` (via the included `WordGate`) give the same
+        # table-driven refusal `TranslationAggregateBuilder` uses.
 
         # Assembles the declared era pair, aggregates and retirements, judged by the translation
         # language.

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

@@ -2,13 +2,8 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
-      # Parses a `value_object "Name" do ... end` block into a
-      # `ValueObject` — its attributes, its own invariants (declared once
-      # and referenceable by name from sibling value objects on the same
-      # aggregate, `RuleReference`), and its `member` rows when it's a
-      # closed set (either bare `one_of` member lines, or the single-field
-      # `attribute ..., one_of: [...]` shorthand `install_inline_closed_set`
-      # installs).
+      # Parses a `value_object "Name" do ... end` block into a `ValueObject`: its attributes,
+      # invariants and, for a closed set, its `member` rows.
       class ValueObjectBuilder
         GRAMMAR_CONTEXT = "ValueObject".freeze
 
@@ -27,64 +22,17 @@ module Hecks
           @owner_value_objects = owner_value_objects
         end
 
-        # The wrapper block is gone (ADR 0025, "Attributes" — "closed sets
-        # lose the wrapper block"). `member` lines are bare now, written
-        # directly in the `value_object` body with no `one_of do ... end`
-        # around them — `build`'s own `closed_set: @closed_set ||
-        # !@members.empty?` already treats a non-empty `@members` as closed,
-        # so nothing else has to change for that to work. A single-field set
-        # has an even shorter spelling: `attribute`'s own `one_of:` keyword
-        # (`AttributeCollector#install_inline_closed_set`, overridden below).
-        #
-        # This also removes a real, documented landmine: the block form
-        # collided with `AttributeCollector#one_of`'s own type-position
-        # method (`one_of("a", "b")`, different arity) the moment both were
-        # mixed into the same builder — a value_object could never actually
-        # use the inline form on one of its own attributes. One `one_of`
-        # method now, not two.
-        #
-        # Legacy under shadow-parsing (S0a's own bridge) — frozen era text
-        # still writes the block form (2 locations in
-        # `examples/banking/data/eras/banking/1.bluebook`, duplicated once
-        # more in that era's own archive copy), so `EraGuard.shadow_parse`
-        # still needs to read it. `block_given?` is what tells the two
-        # calling shapes apart: the type-position form
-        # (`one_of("a", "b")`) never passes a block, only the wrapper does.
-        # Declares this value object as a closed set, either from bare values or (under
-        # shadow-parsing) a legacy `do ... end` wrapper of `member` lines.
-        #
-        # Answers the `one_of` word through the table's `calls:` column —
-        # item #13's full metaprogrammed dispatch
-        # (slice 5). Same name as `AttributeCollector#one_of_impl`'s own
-        # — required for the `super(*values)` call below to keep
-        # resolving; see that method's own comment. Reached directly
-        # through its own "ValueObject"-context Keyword row (the
-        # block-wrapper form has its own row, distinct from "Type"'s),
-        # not through the Type-position fallback this word's other
-        # context uses.
-        #
-        # @param values [Array<String, Symbol>] permitted values, given bare (no block); at
-        #   least one is required
-        # @yield a legacy `member` wrapper body; only read under shadow-parsing
-        # @return [void]
-        # @raise [Bluebook::DSL::Malformed] if given no values and no block, or a block outside
-        #   shadow-parsing
+        # Bare values declare a closed set; the block form is read only under shadow-parsing,
+        # because frozen era text still writes it. Only the wrapper passes a block.
         def one_of_impl(*values, &block)
           unless block
-            # No values, no block is the scalar spelling — nonsensical, not
-            # merely inert: it names a closed set with nothing in it. The
-            # original block form caught this by a side effect (`@closed_set
-            # = true` ran unconditionally, before the `if block`), and this
-            # keeps the same refusal rather than letting the call fall
-            # through and silently do nothing.
+            # 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
 
-            # AttributeCollector's own `one_of(*values)` — Ruby's normal
-            # `super` reaches the included module's method from here.
             return super(*values)
           end
 
@@ -98,62 +46,24 @@ module Hecks
           instance_eval(&block)
         end
 
-        # Declares one member row of a closed set, one value per attribute.
-        #
-        # Answers the `member` word through the table's `calls:` column —
-        # item #13's full metaprogrammed dispatch (slice 4c). Bootstrap-reachable, in
-        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
-        #
-        # @param fields [Hash{Symbol => Object}] each declared attribute's name mapped to this
-        #   member's value for it
-        # @return [Array<Hash{Symbol => Object}>] every member declared so far, this one last
-        # @raise [Bluebook::DSL::Malformed] if `fields` is empty
         def member_impl(**fields)
           raise Malformed, "#{@name} declared an empty member" if fields.empty?
 
           @members << fields
         end
 
-        # No block is a reference, not a fresh declaration — the same
-        # move S10 already made for `CommandBuilder#given` (ADR 0025,
-        # "a precondition shared across commands is declared once... a
-        # command references it by name"), one level over: a rule
-        # shared across sibling value objects on the same aggregate,
-        # declared once, on the first one to need it. Real, live
-        # redundancy this closes: `Account`'s own `Money`/`PositiveMoney`
-        # both declared `invariant("a currency is a three-letter code")
-        # { currency.to_s.size == 3 }`, byte for byte. Declare it before
-        # the value objects that reference it — resolution happens at
-        # the referencing value object's own build time, against
-        # whatever sibling value objects the aggregate has already
-        # built, the same ordering rule `given` carries.
-        # Declares a rule this value object's own value must satisfy, or references one a sibling
-        # value object on the same aggregate already declared.
-        #
-        # Answers the `invariant` word through the table's `calls:` column —
-        # item #13's full metaprogrammed dispatch (slice 4b). Bootstrap-reachable, in
-        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
-        #
-        # @param description [String] the rule's description; also the name a sibling value
-        #   object references it by when no block is given
-        # @yield the predicate body; evaluated for its extracted source, never called directly
-        # @return [void]
-        # @raise [Bluebook::DSL::Malformed] if given a block whose source cannot be extracted or
-        #   uses a pattern construct engines disagree on, or given no block and no sibling value
-        #   object on this aggregate declares a rule with this description
+        # Without a block this references a rule a sibling value object already declared.
+        # Resolution runs at build time, so declare the rule before its referrers.
         def invariant_impl(description, &predicate)
           return reference_named_invariant(description) unless predicate
 
-          # moved to the language: given "a rule says what it means", on Shape.Assert
-
           @invariants << build_rule(Invariant, description, predicate, owner_name: @name, word: "invariant",
                                      extraction_failure: "it would be a rule the IR cannot carry")
         end
 
         private
 
-        # Primitive 3 (RuleReference#resolve_sibling_scan) — see that
-        # method's own comment for why this is a live scan, not a pool.
+        # A live scan of the siblings built so far, not a pool (see RuleReference).
         def reference_named_invariant(description)
           verify_resolves_via!("invariant", "ValueObject", "sibling_scan")
           named = resolve_sibling_scan(@owner_value_objects, description, reader: :invariants) ||
@@ -167,12 +77,6 @@ module Hecks
 
         public
 
-        # Assembles the declared attributes, invariants and members into a `ValueObject`.
-        #
-        # @return [Bluebook::ValueObject] the built value object; `closed_set` is true when any
-        #   member was declared
-        # @raise [Bluebook::DSL::Malformed] if `one_of:` was declared on an attribute alongside
-        #   other attributes on the same value object
         def build
           if @inline_closed_set_field && attributes.size > 1
             raise Malformed,
@@ -188,15 +92,6 @@ module Hecks
           )
         end
 
-        # Evaluates a `value_object` block against a fresh builder and returns what it built.
-        #
-        # @param name [String] the value object's name
-        # @param owner_value_objects [Array<Bluebook::ValueObject>] the owning aggregate's other
-        #   value objects, for `invariant` references to resolve against
-        # @yield the value object body, evaluated with the builder as `self`; may be omitted
-        # @return [Bluebook::ValueObject] the built value object
-        # @raise [Bluebook::DSL::Malformed] if the body declares a rule extraction cannot read,
-        #   `one_of:` on more than one attribute, or uses a word the grammar does not admit
         def self.build(name, owner_value_objects: [], &block)
           builder = new(name, owner_value_objects: owner_value_objects)
           builder.instance_eval(&block) if block
@@ -205,17 +100,8 @@ module Hecks
 
         private
 
-        # **The new spelling** — `attribute :name, String, one_of: %w[...]`,
-        # overriding `AttributeCollector`'s own refusal (every other
-        # includer has no meaningful use for this). Private, like the
-        # module's own version it overrides — it is a callback `attribute`
-        # invokes on itself, never a word a bluebook author calls by name.
-        # Refuses a second attribute naming one_of: on the same value
-        # object outright — a single-field set names exactly one field, by
-        # construction; two would be structurally ambiguous about which
-        # field each member line belongs to. `build` refuses the other
-        # half of that same rule (this attribute coexisting with unrelated
-        # ones on a multi-field object).
+        # 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)
           if @inline_closed_set_field && @inline_closed_set_field != field
             raise Malformed,