hecks 2.7.0 → 2.9.0

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

@@ -1,19 +1,11 @@
 module Hecks
   module Bluebook
     module DSL
-      # Shared mixin for every DSL builder that declares attributes
-      # (Aggregate/Entity/Command/Query/PortOperation/ValueObject) — the
-      # `attribute`/`list_of`/`one_of` words themselves, closed-set
-      # synthesis, duplicate-name and pattern refusals, and the
-      # `identified_by` field/type resolution both a construct's own
-      # identity and a compound key are built from.
+      # Mixin for DSL builders that declare attributes: `attribute`, `list_of`, `one_of`,
+      # closed-set synthesis, and `identified_by` resolution.
       module AttributeCollector
         ListOf = Struct.new(:type)
-        # `:values` shadows Struct#values on purpose — with one member, the
-        # generated accessor returns the flat array of permitted values
-        # directly (what every caller actually wants), not Struct#values'
-        # own `[self.values]`. No caller anywhere reads the built-in
-        # behavior; verified before disabling this cop for it.
+        # `:values` shadows Struct#values so the accessor returns the flat permitted-value array.
         # rubocop:disable-next Lint/StructNewOverride
         OneOf  = Struct.new(:values)
 
@@ -31,73 +23,20 @@ module Hecks
         # @return [Array<Bluebook::ValueObject>] the value objects synthesised so far
         def closed_sets = @closed_sets ||= []
 
-        # Declares one field on the owning construct, with its type and, optionally, a default,
-        # an optionality flag, a pattern, a closed-set reference, or an inline closed set.
-        #
-        # `admits:` names a closed set that is already declared elsewhere —
+        # Declares one field on the owning construct; the type is a bare constant (ADR 0025).
         #
         #   attribute :op, String, admits: "Vocabulary::QueryComparator"
         #
-        # 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
-        # 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`
-        # 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`
-        # 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.
+        # `admits:` names an already-declared closed set as qualified text, checked on read.
+        # `one_of:` declares an inline closed set and is only meaningful inside a `value_object`.
         #
-        # 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
-        # `Name` reaches a value object named "Name" declared later in the
-        # same block, exactly what the quoted form `"Name"` would have
-        # reached — `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.
-        #
-        # The word `attribute` itself is not a real method any builder answers
-        # directly: every (context, word) Keyword row for it carries
-        # `calls: "attribute_impl"`, and `GenericDispatch` forwards the whole
-        # call here untouched. `attribute_collector_spec.rb`
-        # (`AttributeCollector has no method without a test` —
-        # dsl_coverage_spec.rb) and the bootstrap fallback
-        # (`GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`) both name this same
-        # string; they must never drift apart.
-        #
-        # @param name [Symbol] the attribute's name
-        # @param type [Module, Symbol, ListOf, OneOf] the attribute's type: a bare constant
-        #   (resolved by `ConstShim`), or the `ListOf`/`OneOf` wrapper `list_of`/`one_of` return
-        #   when called in this same type position; quoted text is refused
-        # @param default [Object, nil] the value an omitted attribute defaults to; not type-checked
-        #   here
-        # @param optional [Boolean] whether the attribute may be omitted entirely
-        # @param pattern [Regexp, String, nil] a pattern the attribute's value must match; refused
-        #   if it uses a construct `PatternSubset` disallows
-        # @param admits [String, nil] the qualified name of an already-declared closed set this
-        #   attribute's value may come from, such as `"Vocabulary::QueryComparator"`
-        # @param one_of [Array<String, Symbol>, nil] permitted values for a field-shaped closed
-        #   set, declared inline via `one_of: [...]`; meaningful only inside a `value_object`
-        #   (`ValueObjectBuilder` overrides `install_inline_closed_set`) — refused everywhere else
+        # @param type [Module, ListOf, OneOf] a bare constant or a `list_of`/`one_of` wrapper
         # @return [void]
-        # @raise [Bluebook::DSL::Malformed] if `name` is already declared, `type` is omitted or
-        #   quoted text, `pattern` uses a disallowed construct, or `one_of:` is given outside a
-        #   `value_object`
+        # @raise [Malformed] on a duplicate name, a missing or quoted type, a disallowed
+        #   pattern, or `one_of:` outside a `value_object`
         def attribute_impl(name, type = UNSET, default: nil, optional: false, pattern: nil,
                            admits: nil, one_of: nil)
-          # moved to the language: FieldName invariant, on Root.Attribute
+          # The FieldName invariant on Root.Attribute enforces the name.
 
           refuse_duplicate_attribute!(name)
 
@@ -106,10 +45,7 @@ module Hecks
                              "there is no default"
           end
 
-          # `list_of("X")` carries the same quoted text one level down — a
-          # bare constant is required there too, checked before it unwraps
-          # below, not after (once unwrapped, a plain String in the `type:`
-          # slot looks identical to one that legitimately belongs there).
+          # `list_of("X")` carries quoted text one level down; check it before unwrapping.
           quoted = type.is_a?(ListOf) ? type.type : type
           if quoted.is_a?(::String)
             raise Malformed, "#{name}'s type #{quoted.inspect} is quoted text — give the bare constant " \
@@ -134,73 +70,24 @@ module Hecks
           install_inline_closed_set(name, one_of) if one_of
         end
 
-        # Wraps a type so `attribute_impl` records it as a list-valued attribute.
-        #
-        # 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 via
-        # `WordGate#word_gate_dispatch`'s "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 context —
-        # the bootstrap branch checks that key too, same reasoning as the
-        # ordinary fallback.
+        # Wraps a type so `attribute_impl` records it as list-valued: `attribute :x, list_of(Y)`.
         #
-        # @param type [Module, Symbol] the list's element type, a bare constant
-        # @return [Bluebook::DSL::AttributeCollector::ListOf] the wrapper `attribute_impl` reads
-        #   to mark the attribute list-valued
+        # Reached through WordGate's "Type"-context fallback; one `["Type", "list_of"]` entry in
+        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK covers bootstrap.
         def list_of_impl(type) = ListOf.new(type)
 
-        # `reference_to Account` mints `:account` — no `_id` — the default
-        # every `reference_to`-shaped word (`AggregateBuilder`,
-        # `EntityBuilder`, `CommandBuilder#cross_reference`,
-        # `QueryBuilder`, `PortOperationBuilder`, all `include
-        # AttributeCollector`) shares, since dropping the suffix is what
-        # makes `/` a real traversal operator possible at all (ADR 0025,
-        # "References" — a hop crosses at `/`, a field walk crosses at
-        # `.`; 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
-        # refuse a spelling the way S1's `identified_by` legacy forms do.
-        # 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.
+        # `reference_to Account` mints `:account`, no `_id` (ADR 0025). Under shadow-parsing the
+        # suffix is kept so frozen era text reconstructs the name it was minted under.
         private def default_reference_name(target)
           suffix = MetaValidator.shadow_parsing? ? "_id" : ""
           :"#{Naming.snake(target)}#{suffix}"
         end
 
-        # A closed set declared inline on the attribute:
+        # Wraps permitted values so `attribute_impl` synthesises a closed-set value object:
         #
         #   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
-        # structural rule rather than a predicate.
-        #
-        # Wraps a list of permitted values so `attribute_impl` synthesises a closed-set value
-        # object for them.
-        #
-        # The desugaring is pinned — the same bluebook must always yield the
-        # same IR, so a plain String attribute silently discarding the
-        # values is not an outcome this spelling can produce.
-        #
-        # Reached the same way `list_of_impl` above is. 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
-        # chain, and renaming only one side would silently break it.
-        #
-        # @param values [Array<String, Symbol>] the permitted values
-        # @return [Bluebook::DSL::AttributeCollector::OneOf] the wrapper `attribute_impl` reads to
-        #   synthesise the closed-set value object
+        # Shares its name with `ValueObjectBuilder#one_of_impl`, whose `super` resolves by name.
         def one_of_impl(*values) = OneOf.new(values)
 
         private
@@ -216,46 +103,24 @@ module Hecks
           )
         end
 
-        # `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
-        # multi-field set still writes bare `member` lines, unwrapped).
-        # `ValueObjectBuilder` overrides this; every other includer
-        # (Aggregate/Entity/Command/Query/PortOperation) inherits this
-        # refusal — those contexts already have the unchanged type-position
-        # form (`attribute :status, one_of("open", "shut")`) for an
-        # anonymous inline set, so `one_of:` naming a *field* there would be
-        # a second spelling of the same idea, not a new one.
+        # `one_of:` on a field is meaningful only inside a `value_object` (ADR 0025);
+        # ValueObjectBuilder overrides this and every other includer refuses.
         def install_inline_closed_set(name, _values)
           raise Malformed,
                 "#{name}'s one_of: only means something inside a value_object — name a closed set " \
                 "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
-        # 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 — left unrefused, both declarations would
-        # survive into the IR, one of them permanently 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.
+        # Refused where every owner mints an attribute: readers look names up with `find`/`any?`
+        # and would silently discard the second declaration.
         def refuse_duplicate_attribute!(name)
           return unless attributes.any? { |attribute| attribute.name == name }
 
           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 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.
+        # Refused at declaration: a regex whose meaning depends on the engine must not load
+        # (PatternSubset says which constructs and why).
         def refuse_unshared_pattern(name, pattern)
           rejection = PatternSubset.validate(pattern)
           return unless rejection
@@ -276,27 +141,12 @@ module Hecks
           type
         end
 
-        # Every selected identity head contributes all of its recursively
-        # scalar leaves in declaration order. Named, inline and compound-key
-        # declarations therefore share one flattening rule.
+        # Each selected identity head contributes all its scalar leaves in declaration order.
         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-
-          # 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
-          # `behavior.bluebook`'s own "owner_id is not a declared
-          # attribute" comment); bare `:id` is `Instance#materialize_
-          # identity!`'s own fallback name (`@aggregate.identified_by ||
-          # :id`) made explicit rather than left implicit — declaring
-          # `identified_by :id` says out loud what omitting `identified_by`
-          # entirely already meant. `reference_to` mints the `_id` suffix
-          # for the same reason `attr.reference?` below resolves bare: an
-          # `_id`(-shaped) name is already a scalar by the language's own
-          # spelling convention, walk-supplied or locally declared alike.
+          # A bare `:id` or `_id`-suffixed name with no matching attribute is the walk-parent/
+          # fallback-identity convention (Instance#materialize_identity! falls back to `:id`).
           return [field.to_s] if attr.nil? && (field.to_s == "id" || field.to_s.end_with?("_id"))
 
           raise Malformed, "#{context_name}.identified_by :#{field} names no attribute #{context_name} declares" unless attr
@@ -321,26 +171,11 @@ 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
-          # 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
-          # `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".
+          # `Attribute.new` directly: `vo` is an anonymous class whose `to_s` would spell
+          # "#<Class:0x...>", so the demodulised `target` text is the type.
           attributes << Attribute.new(name: field, type: target)
-          # 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
-          # 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
-          # and an attribute — this matches either, producing the same
-          # result a person hand-writing `attribute field, Type` at that
-          # exact point would.
+          # Moved to `insert_at`, the attribute count when `identified_by` was called; resolution
+          # runs at build time, so appending would put the identity field last.
           attributes.insert(insert_at, attributes.pop)
           vo.attributes.flat_map do |attribute|
             identity_paths_for_attribute(attribute, value_objects, context_name,
@@ -368,14 +203,8 @@ 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
-          # of a compound `identified_by :a, :b`) names a single field, and
-          # 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. Left unrefused, a
-          # multi-field value object here would expand silently into every
-          # one of its own fields, minting an unannounced compound key
-          # nothing declared.
+          # A bare field derives one scalar, so each value object on the way must wrap exactly one
+          # field (ADR 0025); otherwise it would silently mint an unannounced compound key.
           if nested.attributes.size != 1
             candidates = nested.attributes.map(&:name).join(", ")
             raise Malformed,

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

@@ -1,19 +1,10 @@
 module Hecks
   module Bluebook
     module DSL
-      # What a bare `Domain::Aggregate` constant resolves to inside a
-      # `.hecksagon`/`.world` block (minted by `.namespace`'s own
-      # `const_missing`) — `method_missing` turns a bind like
-      # `Payment.persisted_by "Postgres"` into a queued `Bind`, and `#port`
-      # is the one real method, for `Aggregate.port("Name") do ... end`.
+      # What a bare `Domain::Aggregate` constant resolves to inside a `.hecksagon`/`.world`
+      # block; `method_missing` records a bind, `#port` is the one real method on this proxy.
       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"`
+        # Mints the module a bare `Domain::Aggregate` constant resolves to via `const_missing`.
         def self.namespace(domain, collector)
           Module.new do
             define_singleton_method(:const_missing) do |aggregate|
@@ -22,48 +13,26 @@ 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
 
-        # 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
-        # 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
+        # Declares a port on this aggregate. A real method, not method_missing — its
+        # shape (name plus an operations block) is unrelated to `Bind`'s generic verb path.
         def port(name, &block)
           domain, aggregate_name = @fqn.split("::")
           aggregate_ir = Hecks.current_registry.bluebook(domain)&.aggregate(aggregate_name) or
             raise Malformed, "#{@fqn} declares no such aggregate — a port needs one to belong to"
 
-          # See HecksagonBuilder#port's own comment on why this resolver
-          # swap is needed : ConstShim's active resolver is one global for
-          # the whole dynamic extent, and it is currently this file's own
-          # BindingProxy-minting one, which would turn a bare `Pizza` inside
-          # `reference_to Pizza` into another BindingProxy instead of a name.
+          # ConstShim's resolver is one global for the whole dynamic extent; without
+          # swapping it here, a bare `Pizza` inside `reference_to Pizza` would resolve
+          # to another BindingProxy instead of a plain name.
           built = ConstShim.with(->(const) { const }) { DomainPortBuilder.build(name, owner: aggregate_name, &block) }
 
-          # A `verb`-shaped port is a plain `Port` — the exact struct
-          # `Hecks.port`'s own top-level method registers, so it goes
-          # through the same `add_port` the registry already answers for
-          # that call. It belongs to no aggregate IR the way an
-          # operations-shaped `DomainPort` does; the aggregate above
-          # was only needed to resolve `owner` for the operations branch.
+          # A `verb`-shaped port is a plain `Port`, the same struct `Hecks.port`
+          # registers — it belongs to no aggregate IR the way an operations-shaped
+          # `DomainPort` does, so it takes the registry's `add_port` directly.
           if built.is_a?(Port)
             Hecks.current_registry.add_port(built)
             return self
@@ -77,14 +46,9 @@ module Hecks
         end
 
         def method_missing(verb, *args, **kwargs, &block)
-          # A BARE CALL — no args, no kwargs, no block — starts (or
-          # continues, on `AttributePath` itself below) a Privacy
-          # marking chain: `Registration.attendee.medications.has_phi(
-          # readable_by: "Privacy officer")`. No existing real
-          # `.hecksagon` bind is ever called this way (verified by
-          # grep before adding this branch — `persisted_by`/
-          # `opened_by`/every other bind always takes at least one
-          # arg), so this cannot collide with recording a `Bind`.
+          # A bare call (no args/kwargs/block) starts a Privacy marking chain instead
+          # of a Bind — no real `.hecksagon` bind is ever called with zero arguments,
+          # so this can't collide with recording one.
           return AttributePath.new(@fqn, [verb.to_s]) if args.empty? && kwargs.empty? && !block
 
           @collector << Bind.new(
@@ -102,27 +66,15 @@ module Hecks
         def to_s = @fqn
       end
 
-      # What a Privacy-marking chain resolves to after its first bare segment —
-      # `Registration.attendee` returns one of these, `.medications` returns another
-      # (one segment longer), and a terminal `has_<category>(readable_by:)` records the
-      # marking and ends the chain. See `BindingProxy#method_missing`'s own header for why
-      # a bare call is unambiguously the start of one of these, never a `Bind`.
+      # What a Privacy-marking chain resolves to after its first bare segment — each
+      # bare call extends the path one segment; a terminal `has_<category>(readable_by:)` ends it.
       class AttributePath
-        # @param fqn [String] the aggregate's own qualified name, `"Domain::Aggregate"`
-        # @param path [Array<String>] every segment named so far, e.g. `["attendee"]`
         def initialize(fqn, path)
           @fqn  = fqn
           @path = path
         end
 
-        # @param verb [Symbol] `has_<category>` to record the marking and end the chain;
-        #   any other bare name to extend the path one segment further
-        # @param readable_by [String] required only for a `has_<category>` call — the
-        #   Governance role a read must hold to see this field unredacted
-        # @return [Bluebook::DSL::AttributePath, nil] a longer chain for a plain segment;
-        #   `nil` (nothing further to chain) for a `has_<category>` call
-        # @raise [Malformed] if a `has_<category>` call omits `readable_by:`, or any call
-        #   carries positional args or a block (neither shape this chain supports)
+        # Records a `has_<category>` marking, or extends the attribute path by one segment.
         def method_missing(verb, *args, readable_by: nil, **kwargs, &block)
           name = verb.to_s
           return record_marking(name.delete_prefix("has_"), readable_by) if name.start_with?("has_")