hecks 1.4.0 → 1.5.0

data/lib/hecks/bluebook/behaviour/process_manager.rb

@@ -5,6 +5,10 @@ module Hecks
       # the states and the handlers; the compensation half — `saga` — is
       # derived from the handler that answers a refusal, not declared.
       module ProcessManager
+        # The bluebook's name for this construct.
+        #
+        # @return [String, nil] the process manager's declared name, or `nil` before it
+        #   is set
         def hecks_name = @name
 
         # The leg that answers — selected by (event, current state), C10.3
@@ -17,12 +21,27 @@ module Hecks
         # selection). Build refuses two legs on one (event, state) pair
         # (`ProcessManagerBuilder#validate!`), so a stated lookup is
         # unambiguous by construction.
+        #
+        # @param event [String, Symbol] the triggering event's name
+        # @param state [String, Symbol, nil] the instance's current state; `nil` asks
+        #   declaratively, ignoring state
+        # @return [Bluebook::ProcessManagerHandler, nil] the matching handler row, or `nil`
+        #   if no declared leg answers this (event, state) pair
         def handler_for(event, state = nil)
           @handlers.find { |h| h.event_type == event.to_s && (state.nil? || h.from_state == state.to_s) }
         end
 
+        # Finds every declared leg for an event, regardless of source state.
+        #
+        # @param event [String, Symbol] the triggering event's name
+        # @return [Array<Bluebook::ProcessManagerHandler>] every handler row declared for
+        #   `event`; `[]` if none is declared
         def handlers_for(event) = @handlers.select { |h| h.event_type == event.to_s }
 
+        # Says whether any declared leg answers an event.
+        #
+        # @param event [String, Symbol] the triggering event's name
+        # @return [Boolean] whether any handler row is declared for `event`
         def handles?(event) = @handlers.any? { |h| h.event_type == event.to_s }
 
         # Whether a state is one this procedure declares — asked of a value
@@ -30,15 +49,24 @@ module Hecks
         # state), the way `Lifecycle#states` is asked of an aggregate's
         # resting field. A rehydrated instance in a state no handler could
         # have reached is corruption the durable round-trip introduced.
+        #
+        # @param state [String, Symbol] the state to check
+        # @return [Boolean] whether `state` is one of this procedure's declared states
         def declares_state?(state) = @states.map(&:to_s).include?(state.to_s)
 
+        # Names the payload field a triggering event's instances are correlated by.
+        #
+        # @return [Symbol] the head of `correlates_by` — the part before the first `.`
         def correlation_head = @correlates_by.to_s.split(".").first.to_sym
 
         # The compensation half of a procedure, read off the handler that
-        # answers REFUSED.
+        # answers `REFUSED`.
         #
         # nil for a procedure with no answer to a refusal, which is a legitimate
         # thing to be — a hiring pipeline cannot un-interview anybody.
+        #
+        # @return [Bluebook::Saga, nil] the derived saga, or `nil` if no handler answers
+        #   `REFUSED`
         def saga
           leg = handler_for(Bluebook::ProcessManager::REFUSED)
           return nil unless leg
@@ -60,6 +88,9 @@ module Hecks
                              to_state: leg.to_state, compensations: derived + leg.dispatches)
         end
 
+        # Says whether this procedure declares a handler for `REFUSED`.
+        #
+        # @return [Boolean] whether this procedure has a derivable saga
         def saga? = !saga.nil?
       end
     end

data/lib/hecks/bluebook/behaviour/query.rb

@@ -3,6 +3,11 @@ module Hecks
     module Behaviour
       # What a query does beyond holding its declared shape.
       module Query
+        # Finds a declared result attribute by name.
+        #
+        # @param named [String, Symbol] the attribute's declared name
+        # @return [Bluebook::Attribute, nil] the attribute, or `nil` if none is declared
+        #   by that name
         def attribute(named) = @attributes.find { |a| a.name == named.to_sym }
       end
     end

data/lib/hecks/bluebook/behaviour/read_model.rb

@@ -4,14 +4,22 @@ module Hecks
       # **What a read model does**. Its declared half is the gathered heads
       # and the query shape; these are readings taken off them.
       module ReadModel
+        # Lists the fields this read model groups rows by.
+        #
+        # @return [Array<Symbol>] each declared `group_by` field's name, in declaration order
         def group_by_fields = @group_by.map { |row| row[:field].to_sym }
 
         # `!!` rather than a bare `@count` — the DSL/reconstruction
         # boundary (ReadModel#initialize) already normalises to
         # `true`/`nil`, so this is belt and braces against a future
         # caller constructing a ReadModel by hand with `count: false`.
+        #
+        # @return [Boolean] whether this read model reduces to a row count
         def count? = !!@count
 
+        # Names the verb `Dispatcher#query` looks this read model up by.
+        #
+        # @return [String] this read model's name in `snake_case`
         def query_name = Naming.snake(@name)
 
         # Which gathered heads the filtering applies to (ADR 0055) — plural,
@@ -22,6 +30,9 @@ module Hecks
         # single-head-only — ADR 0055) applies to it, same as before `on:`
         # existed. With several many-side heads, only the ones actually named
         # by a targeted option are eligible.
+        #
+        # @return [Array<Symbol>] the `:as` name of each many-side head that filtering
+        #   applies to; `[]` if this read model has no many-side head
         def filtered_head_names
           many = @aggregate_heads.select { |head| head[:many] }
           return [] if many.empty?
@@ -37,6 +48,11 @@ module Hecks
         # `median`, still single-head-only) applies to it — split out only
         # to keep `filtered_head_names` itself under this file's own
         # complexity budget, not because the two questions differ in kind.
+        #
+        # @param many [Array<Hash{Symbol => Object}>] the read model's many-side
+        #   `aggregate_heads` rows; must hold exactly one
+        # @return [Array<Symbol>] `[the one head's :as name]` if any filtering option is
+        #   declared, else `[]`
         def single_filtered_head_name(many)
           declared = wheres.any? || order_by || limit || offset || authorization&.tenant ||
                      @group_by.any? || count? || @median_field
@@ -53,6 +69,11 @@ module Hecks
         # resolves to `head_as`'s own aggregate.
         FilteredOptions = Struct.new(:wheres, :order_by, :limit, :offset, :null_semantics)
 
+        # Scopes this read model's filtering options down to one included head.
+        #
+        # @param head_as [Symbol] the `:as` name of the head to scope filtering to
+        # @return [FilteredOptions] the `wheres`/`order_by`/`limit`/`offset` that apply to
+        #   `head_as`, and this read model's own `null_semantics`
         def options_for(head_as)
           many = @aggregate_heads.select { |head| head[:many] }
           aggregate_name = @aggregate_heads.find { |head| head[:as] == head_as }&.fetch(:aggregate)

data/lib/hecks/bluebook/behaviour/traits.rb

@@ -28,6 +28,10 @@ module Hecks
       # no single head, and answering with the first would be a guess ; the
       # readers that need all of them ask for `identity_heads`.
       module Identified
+        # Derives `identity_paths`, `identity_heads` and the single-head form of
+        # `identified_by` from the declared `identified_by` path(s).
+        #
+        # @return [void]
         def derive_identity
           @identity_paths = Array(@identified_by).map(&:to_s).reject(&:empty?)
           @identity_heads = @identity_paths.map { |path| path.split(".").first.to_sym }.uniq
@@ -48,6 +52,10 @@ module Hecks
       module Indexed
         # Keyed by symbol — an attribute is asked for by its declared
         # symbol name everywhere in the runtime.
+        #
+        # @param attributes [Array<Bluebook::Attribute>] the construct's declared
+        #   attributes
+        # @return [void]
         def index_attributes(attributes)
           @attributes_by_name = attributes.to_h { |held| [held.name, held] }
         end
@@ -56,12 +64,34 @@ module Hecks
         # object is a construct whose Ruby `name` is something else
         # entirely (a constant path, or nothing at all for an anonymous
         # class), so the declared name is the only one worth indexing.
+        #
+        # @param collection [Array<#hecks_name>] declared constructs to index —
+        #   value objects, commands or queries, each answering `hecks_name`
+        # @return [Hash{String => Object}] the collection keyed by each member's
+        #   `hecks_name`
         def index_by_hecks_name(collection)
           collection.to_h { |held| [held.hecks_name, held] }
         end
 
+        # Finds a declared attribute by its declared name.
+        #
+        # @param named [String, Symbol] the attribute's declared name
+        # @return [Bluebook::Attribute, nil] the attribute named `named`, or `nil`
+        #   if none is declared under that name
         def attribute(named) = @attributes_by_name[named.to_sym]
+
+        # Finds a declared command by its declared name.
+        #
+        # @param named [String, Symbol] the command's declared name
+        # @return [Class, nil] the command class (a `Bluebook::Command` subclass)
+        #   named `named`, or `nil` if none is declared under that name
         def command(named)   = @commands_by_name[named.to_s]
+
+        # Finds a declared query by its declared name.
+        #
+        # @param named [String, Symbol] the query's declared name
+        # @return [Bluebook::Query, nil] the query named `named`, or `nil` if none
+        #   is declared under that name
         def query(named)     = @queries_by_name[named.to_s]
       end
 
@@ -72,6 +102,12 @@ module Hecks
       # is complete is the right stamping point: its declarations are
       # final, and nothing outside needs to remember to stamp them.
       module Owns
+        # Stamps each of `children` as owned by this construct.
+        #
+        # @param children [Array<Object>] the construct's own declared children —
+        #   arrays or bare objects, flattened before stamping — each answering
+        #   `hecks_owner=`
+        # @return [void]
         def stamp(*children)
           children.flatten.each { |child| child.hecks_owner = self }
         end

data/lib/hecks/bluebook/behaviour/value_object.rb

@@ -6,13 +6,22 @@ module Hecks
       # behaviour is singleton behaviour, and the holding half's `absorb`
       # is what a generated constructor would be.
       module ValueObject
-        # A one_of declared but left empty used to be indistinguishable from no
-        # one_of at all — both are `members: []` — so the rule about it could
-        # only live in the builder. Recording the declaration lets the language
-        # judge it, the same way an empty attribute name survives into the IR
-        # and is judged there.
+        # Recorded as its own fact (`closed_set`), not left to be inferred from
+        # `members: []` alone — an empty `one_of` and no `one_of` at all would
+        # otherwise be indistinguishable, which would leave the rule about it
+        # only livable in the builder. Recording the declaration lets the
+        # language judge it instead, the same way an empty attribute name
+        # survives into the IR and is judged there.
+        #
+        # @return [Boolean] whether this value object declares `one_of`, even
+        #   if left empty
         def closed_set? = @closed_set
 
+        # Finds a declared attribute by its declared name.
+        #
+        # @param named [String, Symbol] the attribute's declared name
+        # @return [Bluebook::Attribute, nil] the attribute named `named`, or
+        #   `nil` if none is declared under that name
         def attribute(named) = attributes.find { |held| held.name == named.to_sym }
 
         # A single-attribute value object (EmailAddress{address},
@@ -30,6 +39,9 @@ module Hecks
         # `retention_months`/`paper_fee_cents`). `sole_attribute` would
         # return `nil` for that shape and break the discriminant lookup —
         # left as `.first` on purpose, not a missed migration.
+        #
+        # @return [Bluebook::Attribute, nil] this value object's only
+        #   attribute, or `nil` when it has zero or more than one
         def sole_attribute
           attributes.first if attributes.size == 1
         end

data/lib/hecks/bluebook/chapter.rb

@@ -63,6 +63,12 @@ module Hecks
       # ("RoleAssignment.Assign"); `Behaviour::Chapter#provided_verb`
       # qualifies it with the chapter's own name.
       Provision = Struct.new(:capability, :key, :verb, keyword_init: true) do
+        # Coerces one declared or reconstructed `provides` row into a `Provision`.
+        #
+        # @param row [Bluebook::Chapter::Provision, #to_h] a `Provision` already, or
+        #   anything answering `to_h` with `capability`/`key`/`verb` entries
+        # @return [Bluebook::Chapter::Provision] `row` itself if it already is one, else
+        #   a new `Provision` built from its fields
         def self.from(row)
           return row if row.is_a?(self)
 
@@ -74,6 +80,23 @@ module Hecks
       attr_reader :name, :version, :vision, :aggregates, :policies, :process_managers,
                   :classification, :read_models, :ports, :formerly_known_as, :attaches_to, :provides
 
+      # @param name [String, Symbol] the chapter's declared name
+      # @param version [String, Symbol, nil] the chapter's declared business version,
+      #   such as `"v1"`, or `nil` if it declares none
+      # @param vision [String, nil] the chapter's declared vision statement
+      # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
+      # @param policies [Array<Bluebook::Policy>] every reaction declared across the
+      #   chapter's own aggregates, hoisted here
+      # @param process_managers [Array<Bluebook::ProcessManager>] the chapter's declared
+      #   process managers
+      # @param classification [String, Symbol, nil] whether this chapter is central to
+      #   its project's own domain model, or `nil` if undeclared
+      # @param read_models [Array<Bluebook::ReadModel>] the chapter's declared read models
+      # @param formerly_known_as [String, Symbol, nil] an earlier name this domain was
+      #   known under, or `nil` if it was never renamed
+      # @param attaches_to [Array<String, Symbol>] the contexts this chapter attaches to
+      # @param provides [Array<Bluebook::Chapter::Provision, Hash>] the capabilities this
+      #   chapter declares it provides
       def initialize(name:, version: nil, vision: nil, aggregates: [], policies: [],
                      process_managers: [], classification: nil, read_models: [], formerly_known_as: nil,
                      attaches_to: [], provides: [])

data/lib/hecks/bluebook/command.rb

@@ -10,14 +10,12 @@ module Hecks
       include Hecks::IR
       include Behaviour::Mutation
 
-      # `sign:` — item #5 of the whole-project table-unification survey.
-      # `increment`/`decrement`'s own +1/-1 used to be re-derived from the
-      # op name by two independent Rust codegen scripts (rust/project/
-      # mutations.rb, rust/codegen/src/mutations.rs — a ternary on
-      # `op == "increment"` in each), even though the fact was already
-      # table-driven on the Ruby runtime side
-      # (Runtime::CommandRules::Arithmetic::MUTATION_OPS, itself read off
-      # the same generated Vocabulary::MutationOp table).
+      # `sign:` — item #5 of the whole-project table-unification survey:
+      # `increment`/`decrement`'s own +1/-1 comes from `Vocabulary::MutationOp`
+      # here, the same table `Runtime::CommandRules::Arithmetic::MUTATION_OPS`
+      # already reads on the Ruby runtime side, rather than a ternary on the op
+      # name re-deriving it independently in each of two Rust codegen scripts
+      # (rust/project/mutations.rb, rust/codegen/src/mutations.rs).
       # Reads `Vocabulary::MutationOp` directly (plain data, no framework
       # dependency — safe during parsing, same reason `RuleReference`'s
       # own bootstrap concerns don't apply here) rather than requiring
@@ -25,6 +23,11 @@ module Hecks
       # real layering inversion (runtime depends on bluebook, not the
       # reverse). "" (not nil) for ops with no sign, matching every other
       # optional IR text field's own absent-is-empty-string convention.
+      #
+      # @param oper [String, Symbol] the mutation's operation name, such as
+      #   `"increment"` or `"decrement"`
+      # @return [String] the operation's sign from `Vocabulary::MutationOp`
+      #   (`"+"` or `"-"`), or `""` when the op has none or is not found
       def self.sign_for(oper)
         Hecks::Vocabulary.rows("MutationOp").find { |row| row["name"] == oper.to_s }&.fetch("sign", "") || ""
       end
@@ -39,6 +42,10 @@ module Hecks
       # emission covers the fixed head; `super` supplies it and this adds
       # the tail, which is why a construct with a variable shape needs no
       # new mixin API.
+      # @return [Hash{Symbol => Object}] the declared emission — `super`'s fixed
+      #   head, plus `fields:` (a Hash of bound field values) for an
+      #   append-shaped op, or `source:` (`classified_source`'s own result) for
+      #   any other
       def to_h
         return super.merge(fields: appended_fields) if [:append, :delegate, :corrects].include?(op)
 
@@ -95,6 +102,29 @@ module Hecks
         attr_reader :role, :goal, :attributes, :givens, :ensures, :mutations, :emits, :references,
                     :from, :provenance
 
+        # Mints one command as its own anonymous class, a subclass of whichever
+        # `Command`-descended class `declare` is called on.
+        #
+        # @param name [String, Symbol] the command's declared name
+        # @param role [String, nil] the command's declared role text
+        # @param goal [String, nil] the command's declared goal text
+        # @param attributes [Array<Bluebook::Attribute>] the command's declared
+        #   arguments
+        # @param givens [Array<Bluebook::Given>] the command's declared
+        #   preconditions
+        # @param ensures [Array<Bluebook::Given>] the command's declared
+        #   postconditions
+        # @param mutations [Array<Bluebook::Mutation>] the state changes this
+        #   command applies
+        # @param emits [Array<String>] the event names this command may emit
+        # @param references [String, Symbol, nil] the aggregate name this verb's
+        #   `reference_to` addresses, or `nil` for a verb declared on the
+        #   aggregate it acts on
+        # @param from [String, Array<String>, nil] the lifecycle state(s) this
+        #   command is admissible from, or `nil` for no such guard
+        # @param provenance [Object, nil] the command's declared canonical
+        #   source, captured exactly as written, or `nil` if it declares none
+        # @return [Class] the new command class
         def declare(name:, role: nil, goal: nil, attributes: [], givens: [], ensures: [],
                     mutations: [], emits: [], references: nil, from: nil, provenance: nil)
           verb = Class.new(self)
@@ -105,6 +135,21 @@ module Hecks
           verb
         end
 
+        # Assigns what the language declares, then hands off to the behaviour's
+        # own `settle` — indexing attributes, the one thing not derivable from
+        # the declaration.
+        #
+        # @param role [String, nil] see `declare`
+        # @param goal [String, nil] see `declare`
+        # @param attributes [Array<Bluebook::Attribute>] see `declare`
+        # @param givens [Array<Bluebook::Given>] see `declare`
+        # @param ensures [Array<Bluebook::Given>] see `declare`
+        # @param mutations [Array<Bluebook::Mutation>] see `declare`
+        # @param emits [Array<String>] see `declare`
+        # @param references [String, nil] see `declare`
+        # @param from [String, Array<String>, nil] see `declare`
+        # @param provenance [Object, nil] see `declare`
+        # @return [Class] self, once attributes are indexed
         def absorb(role:, goal:, attributes:, givens:, ensures:, mutations:, emits:, references:,
                    from: nil, provenance: nil)
           @role       = role

data/lib/hecks/bluebook/domain_port.rb

@@ -33,6 +33,19 @@ module Hecks
       # what the adapter came back with, `refuses` for what it said instead.
       # Naming only the happy one would put the failure somewhere the model
       # cannot see, which is the whole reason a boundary is worth modelling.
+      #
+      # @param name [String, Symbol] the operation's declared name
+      # @param attributes [Array<Bluebook::Attribute>] the operation's declared payload
+      #   fields
+      # @param emits [Array<String>] the events an inbound operation declares it records
+      # @param direction [Symbol, String] `:inbound` for a `tells`/`operation`, `:outbound`
+      #   for an `asks`
+      # @param answers [String, nil] an outbound operation's declared event for what the
+      #   adapter came back with
+      # @param refuses [String, nil] an outbound operation's declared event for what the
+      #   adapter said instead
+      # @param to [String, nil] the aggregate this operation routes to, or `nil` if it
+      #   declares no routing target
       def initialize(name:, attributes: [], emits: [], direction: :inbound, answers: nil, refuses: nil, to: nil)
         @hecks_name = name.to_s
         @attributes = attributes
@@ -44,7 +57,14 @@ module Hecks
         @attributes_by_name = attributes.to_h { |attribute| [attribute.name, attribute] }
       end
 
+      # Says whether this operation is the domain asking something of an adapter.
+      #
+      # @return [Boolean] whether this operation is an `asks`
       def outbound? = @direction == :outbound
+
+      # Says whether this operation is an adapter telling the domain something.
+      #
+      # @return [Boolean] whether this operation is a `tells`/`operation`
       def inbound?  = @direction == :inbound
 
       # No root reference of its own — unlike a command, every attribute
@@ -72,6 +92,9 @@ module Hecks
       # migrated yet keeps the exact prior IR shape, byte for byte,
       # instead of an unconditional new key breaking parser_parity_spec
       # for every domain that never touched this.
+      #
+      # @return [Hash] the declared emission, plus `direction`/`answers`/`refuses` for an
+      #   outbound operation and `to` when a routing target is declared
       def to_h
         shape = super
         shape = shape.merge(direction: @direction.to_s, answers: @answers, refuses: @refuses) unless inbound?
@@ -93,6 +116,8 @@ module Hecks
 
       attr_reader :name, :operations
 
+      # @param name [String, Symbol] the port's declared name
+      # @param operations [Array<Bluebook::PortOperation>] the port's declared operations
       def initialize(name:, operations: [])
         @name       = name.to_s
         @operations = operations