hecks 1.2.0 → 1.4.0

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

@@ -26,39 +26,39 @@ module Hecks
         # installed by whoever owns value objects (the aggregate).
         def closed_sets = @closed_sets ||= []
 
-        # `admits:` names a closed set that is ALREADY DECLARED elsewhere —
+        # `admits:` names a closed set that is already declared elsewhere —
         #
         #   attribute :op, String, admits: "Vocabulary::QueryComparator"
         #
-        # which is the difference between it and `one_of`: `one_of` SYNTHESISES
+        # which is the difference between it and `one_of`: `one_of` synthesises
         # a fresh value object named for the attribute, so it can only ever name
         # something new. `admits` points at a set the language already holds, so
         # the same set can be named from many places without being written twice.
         #
-        # QUALIFIED, because a closed set is a value object INSIDE an aggregate
+        # Qualified, because a closed set is a value object inside an aggregate
         # and `reference_to` reaches heads only — so this is text, checked where
         # it is read rather than by reference resolution.
         #
-        # AND WRITTEN AS TEXT, not as the constant path `Vocabulary::QueryComparator`
+        # And written as text, not as the constant path `Vocabulary::QueryComparator`
         # it reads like. The constant spelling was tried — `ConstShim` returning
         # a Module so Ruby's `::` reaches a second `const_missing` — and it
         # cannot hold: `Facade::Surface` installs every aggregate name as a
-        # TOP-LEVEL constant, so the moment any facade exists, `Vocabulary`
+        # top-level constant, so the moment any facade exists, `Vocabulary`
         # resolves to that module and the shim is never asked. A spelling that
         # works only until a facade is built is worse than a quoted one.
         #
-        # THE TYPE POSITION TAKES A BARE CONSTANT, ALWAYS REQUIRED (ADR 0025,
+        # The type position takes a bare constant, always required (ADR 0025,
         # "Attributes") — omitting it (a mint default of String) and quoting
         # it as text both refuse now. Neither had a real reason left: no
         # corpus attribute ever omitted the type, and `ConstShim#const_missing`
         # (S0b) already resolves a bare, not-yet-declared constant to the
-        # SAME forward reference the quoted form existed for — a bareword
+        # same forward reference the quoted form existed for — a bareword
         # `Name` reaches a value object named "Name" declared later in the
         # same block exactly as `"Name"` used to, `spell`'s own `to_s`
         # renders either one identically. Neither form appears in any frozen
         # era text (checked directly), so both are refused unconditionally —
         # nothing for `MetaValidator.shadow_parsing?` to answer for.
-        # RENAMED FROM `attribute` — item #13's full metaprogrammed
+        # Renamed from `attribute` — item #13's full metaprogrammed
         # dispatch (slice 3, whole-project table-unification survey).
         # The word `attribute` itself is no longer a real method any
         # builder answers directly: every (context, word) Keyword row
@@ -109,20 +109,20 @@ module Hecks
           install_inline_closed_set(name, one_of) if one_of
         end
 
-        # RENAMED FROM `list_of` — item #13's full metaprogrammed
-        # dispatch (slice 5). Called in an attribute's own TYPE
+        # Renamed from `list_of` — item #13's full metaprogrammed
+        # dispatch (slice 5). Called in an attribute's own type
         # position (`attribute :x, list_of(Y)`), never through a `def
-        # list_of` any ONE builder answers as its own word — reached
+        # list_of` any one builder answers as its own word — reached
         # via `WordGate#word_gate_dispatch`'s new "Type"-context
         # fallback, the same one `one_of_impl` below uses. Bootstrap-
         # reachable (every core chapter's own list-typed attributes use
         # it), so `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK` carries a
-        # SINGLE `["Type", "list_of"]` entry rather than one per calling
+        # single `["Type", "list_of"]` entry rather than one per calling
         # context — the bootstrap branch checks that key too now, same
         # reasoning as the ordinary fallback.
         def list_of_impl(type) = ListOf.new(type)
 
-        # `reference_to Account` MINTS `:account` — no `_id` — the default
+        # `reference_to Account` mints `:account` — no `_id` — the default
         # every `reference_to`-shaped word (`AggregateBuilder`,
         # `EntityBuilder`, `CommandBuilder#cross_reference`,
         # `QueryBuilder`, `PortOperationBuilder`, all `include
@@ -132,13 +132,13 @@ module Hecks
         # `.`; deriving the hop name from `account_id` is what made an
         # explicit operator impossible before).
         #
-        # LEGACY UNDER SHADOW-PARSING (S0a's own bridge): frozen era text
-        # was minted under the OLD default, and `EraGuard.shadow_parse`
-        # reconstructs a held aggregate's shape to DIFF against the
-        # current one — reading that text through the NEW default would
-        # silently reconstruct the WRONG historical name, not merely
+        # Legacy under shadow-parsing (S0a's own bridge): frozen era text
+        # was minted under the old default, and `EraGuard.shadow_parse`
+        # reconstructs a held aggregate's shape to diff against the
+        # current one — reading that text through the new default would
+        # silently reconstruct the wrong historical name, not merely
         # refuse a spelling the way S1's `identified_by` legacy forms do.
-        # This is a mint DEFAULT changing, not a syntax being removed, so
+        # This is a mint default changing, not a syntax being removed, so
         # there is nothing to refuse here — only a fork in what gets
         # minted when `as:` is omitted.
         private def default_reference_name(target)
@@ -146,24 +146,24 @@ module Hecks
           :"#{Naming.snake(target)}#{suffix}"
         end
 
-        # A closed set declared INLINE on the attribute:
+        # A closed set declared inline on the attribute:
         #
         #   attribute :status, one_of("open", "shut")
         #
         # Desugars to a value object named for the attribute, so it goes through
         # exactly the machinery a hand-written one_of does — and so the
-        # attribute's type is still a DECLARED value object, which is now a
+        # attribute's type is still a declared value object, which is now a
         # structural rule rather than a predicate.
         #
         # An earlier reading of this spelling parsed it and threw the values
         # away: the attribute became a plain String and the closed set meant
         # nothing, in a construct that looked supported. The desugaring is
         # pinned now — the same bluebook must always yield the same IR.
-        # RENAMED FROM `one_of` — item #13's full metaprogrammed dispatch
-        # (slice 5), same reasoning as list_of_impl above. SAME NAME as
+        # Renamed from `one_of` — item #13's full metaprogrammed dispatch
+        # (slice 5), same reasoning as list_of_impl above. Same name as
         # `ValueObjectBuilder#one_of_impl`'s own override on purpose —
         # that method's own `super(*values)` call (the no-block, bare
-        # type-position case) resolves by METHOD NAME up the ancestor
+        # type-position case) resolves by method name up the ancestor
         # chain, and renaming only one side would silently break it.
         def one_of_impl(*values) = OneOf.new(values)
 
@@ -180,11 +180,11 @@ module Hecks
           )
         end
 
-        # `one_of:` NAMES A CLOSED SET ON THE FIELD ITSELF (ADR 0025,
+        # `one_of:` names a closed set on the field itself (ADR 0025,
         # "Attributes") — joining `pattern:`/`admits:` where value
         # constraints already live, for the one context where it means
         # anything: a `value_object` block, where it replaces the old
-        # `one_of do member ... end` wrapper for a SINGLE-FIELD set (a
+        # `one_of do member ... end` wrapper for a single-field set (a
         # multi-field set still writes bare `member` lines, unwrapped).
         # `ValueObjectBuilder` overrides this; every other includer
         # (Aggregate/Entity/Command/Query/PortOperation) inherits this
@@ -198,15 +198,15 @@ module Hecks
                 "with the type-position one_of(...) instead"
         end
 
-        # A NAME DECLARED TWICE ON THE SAME OWNER IS TWO ATTRIBUTES SHARING
-        # ONE NAME, and nothing downstream disambiguates them — every
+        # A name declared twice on the same owner is two attributes sharing
+        # one name, and nothing downstream disambiguates them — every
         # reader that walks `attributes` looking for one by name
         # (`seal_mutation_targets`, `seal_query_field`, `projects`'s own
         # local check, `Instance#[]`, ...) uses `Array#find`/`any?`, which
         # silently answers whichever declaration happens to come first and
         # discards the second. Used to boot clean and stay that way : both
         # declarations survived into the IR, one of them permanently
-        # unreachable by name. Refused HERE, at the one place every owner
+        # unreachable by name. Refused here, at the one place every owner
         # (Aggregate/Entity/Command/Query/PortOperation/ValueObject, each
         # `include AttributeCollector`) mints an attribute through, rather
         # than taught to each of those readers individually.
@@ -216,7 +216,7 @@ module Hecks
           raise Malformed, "#{name} is declared twice — an attribute name is declared once, not twice"
         end
 
-        # A pattern is refused AT DECLARATION, not when a value first meets it :
+        # A pattern is refused at declaration, not when a value first meets it :
         # a regex whose meaning depends on which engine reads it is a defect in
         # the bluebook, and a bluebook that loads is one whose patterns carry
         # one meaning. PatternSubset says which those are, and why each is refused.
@@ -246,9 +246,9 @@ module Hecks
         def resolve_identity_field!(field, value_objects, context_name)
           attr = attributes.find { |a| a.name == field }
 
-          # `:id` OR AN `_id`-SUFFIXED NAME WITH NO MATCHING ATTRIBUTE is
-          # not a typo to refuse — it is the language's own WALK-PARENT/
-          # FALLBACK-IDENTITY convention. The `_id` suffix is the meta-
+          # `:id` or an `_id`-suffixed name with no matching attribute is
+          # not a typo to refuse — it is the language's own walk-parent/
+          # fallback-identity convention. The `_id` suffix is the meta-
           # domain's own (the `Command`/`Entity`/`Aggregate` etc. records
           # identify by `owner_id`/`bluebook_id`/`aggregate_id`, supplied
           # by the judge's replay rather than declared locally — see
@@ -285,20 +285,20 @@ module Hecks
                   "#{context_name}.identified_by #{target} mints :#{field}, but that attribute is already declared"
           end
 
-          # `Attribute.new` DIRECTLY, not the public `attribute(...)` DSL
-          # entry — `target` is `Naming.demodulise`'d TEXT, not a bareword
+          # `Attribute.new` directly, not the public `attribute(...)` DSL
+          # entry — `target` is `Naming.demodulise`'d text, not a bareword
           # the bluebook author typed (the type position's own quoted-text
           # refusal is about DSL source, not internal minting), and `vo`
-          # ITSELF can't be passed either: it is the real, already-built
+          # itself can't be passed either: it is the real, already-built
           # `ValueObject` subclass, permanently anonymous from Ruby's own
           # `to_s` (only `hecks_name` carries its name) — `Attribute#spell`
           # would demodulise it to "#<Class:0x...>", not "PizzaName".
           attributes << Attribute.new(name: field, type: target)
-          # MOVED to `insert_at` — the attribute count AT THE MOMENT
+          # Moved to `insert_at` — the attribute count at the moment
           # `identified_by` was actually called, captured by the caller —
           # not left where `attribute` just appended it. Resolution happens
-          # at BUILD time, after every other attribute in the block has
-          # already run, so appending would put the identity field LAST
+          # at build time, after every other attribute in the block has
+          # already run, so appending would put the identity field last
           # regardless of where `identified_by` was actually written.
           # Most real bluebooks write it first (insert_at 0); one (a
           # ScheduledPayment corpus member) writes it after a reference_to
@@ -332,9 +332,9 @@ module Hecks
             raise Malformed, "#{context_name}'s identity value objects form a cycle: #{cycle}"
           end
 
-          # A BARE FIELD DERIVES ONE SCALAR. `identified_by :ref` (or one leg
+          # **A bare field derives one scalar**. `identified_by :ref` (or one leg
           # of a compound `identified_by :a, :b`) names a single field, and
-          # deriving ITS path only makes sense while every value object along
+          # deriving its path only makes sense while every value object along
           # the way wraps exactly one field itself — the same "single-field
           # value object" ADR 0025 names this shape after. A multi-field
           # value object here used to expand silently into every one of its

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

@@ -7,6 +7,13 @@ module Hecks
       # `Payment.persisted_by "Postgres"` into a queued `Bind`, and `#port`
       # is the one real method, for `Aggregate.port("Name") do ... end`.
       class BindingProxy
+        # Mints the stand-in module a bare domain constant resolves to inside a `.hecksagon` block.
+        #
+        # @param domain [Symbol, String] the domain name, the first segment of `Domain::Aggregate`
+        # @param collector [Array<Bluebook::Bind>] the list every bind made through the module's
+        #   proxies is appended to
+        # @return [Module] an anonymous module whose `const_missing` answers a `BindingProxy`
+        #   for `"Domain::Aggregate"`
         def self.namespace(domain, collector)
           Module.new do
             define_singleton_method(:const_missing) do |aggregate|
@@ -15,17 +22,30 @@ module Hecks
           end
         end
 
+        # @param fqn [String] the aggregate's qualified name, `"Domain::Aggregate"`
+        # @param collector [Array<Bluebook::Bind>] the list each bind made on this proxy is
+        #   appended to
         def initialize(fqn, collector)
           @fqn       = fqn
           @collector = collector
         end
 
-        # THE AGGREGATE-SCOPED PORT — `Payments::Payment.port("Gateway") do
+        # Declares a port on this aggregate and attaches it to the already-registered bluebook.
+        #
+        # **The aggregate-scoped port** — `Payments::Payment.port("Gateway") do
         # ... end`, the same receiver a plain bind like `.persisted_by(...)`
         # already reaches, because a port belongs to exactly one aggregate
-        # the same way a bind does. A REAL method, not method_missing : its
+        # the same way a bind does. A real method, not method_missing : its
         # shape (a name and a block building operations) has nothing to do
         # with `Bind`, so it does not belong in that generic verb path.
+        #
+        # @param name [String] the port's name, such as `"Gateway"`
+        # @yield the port body, evaluated against a `DomainPortBuilder`: either `verb`/`signal`
+        #   or `operation`/`tells`/`asks` blocks
+        # @return [Bluebook::DSL::BindingProxy] this proxy, so further binds can chain
+        # @raise [Bluebook::DSL::Malformed] if the current registry holds no such aggregate, or
+        #   the body declares both a verb and operations, neither, or an operation the port
+        #   grammar refuses
         def port(name, &block)
           domain, aggregate_name = @fqn.split("::")
           aggregate_ir = Hecks.current_registry.bluebook(domain)&.aggregate(aggregate_name) or