hecks 1.3.0 → 1.5.0

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

@@ -20,56 +20,81 @@ module Hecks
         UNSET = Object.new.freeze
         private_constant :UNSET
 
+        # Returns the attributes declared so far, minting the accumulating list on first use.
+        #
+        # @return [Array<Bluebook::Attribute>] the attributes declared so far, in declaration order
         def attributes = @attributes ||= []
 
         # Value objects synthesised from inline closed sets, collected here and
         # installed by whoever owns value objects (the aggregate).
+        #
+        # @return [Array<Bluebook::ValueObject>] the value objects synthesised so far
         def closed_sets = @closed_sets ||= []
 
-        # `admits:` names a closed set that is ALREADY DECLARED elsewhere —
+        # 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 —
         #
         #   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
-        # 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
-        # for it carries `calls: "attribute_impl"`, and `GenericDispatch`
-        # forwards the whole call here untouched — this method's own
-        # body is exactly what `attribute` always was, unchanged, just
-        # reached generically now rather than by Ruby's own direct
-        # method lookup. `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.
+        # 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
+        # @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`
         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
@@ -109,20 +134,25 @@ 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
-        # 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 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
-        # context — the bootstrap branch checks that key too now, same
-        # reasoning as the ordinary fallback.
+        # 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.
+        #
+        # @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
         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 +162,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,25 +176,31 @@ 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
+        # 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
+        # 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
         def one_of_impl(*values) = OneOf.new(values)
 
         private
@@ -180,11 +216,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 +234,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
+        # 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.
@@ -216,7 +252,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 +282,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,26 +321,26 @@ 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
-          # and an attribute — this matches either, and whatever a person
-          # hand-writing `attribute field, Type` at that exact point,
-          # the way this used to be required, would have produced.
+          # and an attribute — this matches either, producing the same
+          # result a person hand-writing `attribute field, Type` at that
+          # exact point would.
           attributes.insert(insert_at, attributes.pop)
           vo.attributes.flat_map do |attribute|
             identity_paths_for_attribute(attribute, value_objects, context_name,
@@ -332,13 +368,14 @@ 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
-          # own fields, minting an unannounced compound key nothing declared.
+          # 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.
           if nested.attributes.size != 1
             candidates = nested.attributes.map(&:name).join(", ")
             raise Malformed,

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
@@ -57,6 +77,16 @@ 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`.
+          return AttributePath.new(@fqn, [verb.to_s]) if args.empty? && kwargs.empty? && !block
+
           @collector << Bind.new(
             aggregate: @fqn,
             verb:      verb.to_s,
@@ -71,6 +101,55 @@ 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`.
+      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)
+        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_")
+
+          if !args.empty? || !kwargs.empty? || block
+            raise Malformed, "#{@fqn}.#{@path.join('.')}.#{name} — an attribute path chain takes no " \
+                             "arguments except a terminal has_<category>(readable_by:)"
+          end
+
+          AttributePath.new(@fqn, @path + [name])
+        end
+
+        def respond_to_missing?(_name, _include_private = false) = true
+
+        def to_s = "#{@fqn}.#{@path.join('.')}"
+
+        private
+
+        def record_marking(category, readable_by)
+          raise Malformed, "#{self}.has_#{category} needs readable_by: (the Governance role a read must hold)" unless readable_by
+
+          Hecks.current_registry.add_pending_privacy_marking(
+            domain: @fqn, attribute_path: @path.join("."), category: category, readable_by: readable_by
+          )
+          nil
+        end
+      end
     end
   end
 end