hecks 2.8.0 → 2.9.0

data/lib/hecks/bluebook/hexagon.rb

@@ -4,44 +4,24 @@ require_relative "../ir"
 module Hecks
   module Bluebook
     Port = Struct.new(:name, :verb, :signal, :answers, keyword_init: true) do
-      # Says whether this port answers its verb with a return value.
-      #
-      # @return [Boolean] whether `signal` is `:reply`
       def reply?  = signal == :reply
 
-      # Says whether this port answers its verb by taking effect, with no return value.
-      #
-      # @return [Boolean] whether `signal` is `:effect`
       def effect? = signal == :effect
     end
 
     Adapter = Struct.new(:name, :port, :fields, :secrets, keyword_init: true) do
-      # Says whether this adapter declares a field, plain or secret.
-      #
-      # @param field [Symbol, String] the field to check
-      # @return [Boolean] whether `field` is one of this adapter's own `fields` or `secrets`
       def declares?(field) = all_fields.include?(field.to_sym)
 
-      # Lists every field this adapter declares, plain and secret alike.
-      #
-      # @return [Array<Symbol>] every field this adapter declares, `fields` and `secrets`
-      #   combined
       def all_fields = (fields || []) + (secrets || [])
     end
 
     Bind = Struct.new(:aggregate, :verb, :adapter, :role, keyword_init: true) do
-      # Names the aggregate this bind applies to.
-      #
-      # @return [String] this bind's aggregate name, demodulised, or `""` for a
-      #   domain-level default bind with no aggregate
+      # Empty for a domain-level default bind with no aggregate.
       def aggregate_name = Naming.demodulise(aggregate)
     end
 
-    # The built form of a `.hecksagon` file, produced by
-    # `DSL::HecksagonBuilder` — a domain's own binds (`Bind`, above),
-    # subscriptions, and attached framework/vendored members.
-    # `Behaviour::Hecksagon` supplies the bind lookups (`bind_for`/
-    # `binds_for`); this class holds only the declared data.
+    # The built form of a `.hecksagon` file, produced by `DSL::HecksagonBuilder`.
+    # `Behaviour::Hecksagon` supplies the bind lookups; this class holds the declared data.
     class Hecksagon
       include Hecks::IR
       include Behaviour::Hecksagon
@@ -88,11 +68,8 @@ module Hecks
       def bounded? = @bounded
     end
 
-    # The built form of a `.world` file, produced by `DSL::WorldBuilder` —
-    # a domain's own `realm`/`latest` version markers and its adapter bind
-    # settings (as opposed to `Hecksagon`'s own bind list, above).
-    # `Behaviour::World` supplies the settings lookups (`for_verb`/
-    # `for_binding`); this class holds only the declared data.
+    # The built form of a `.world` file, produced by `DSL::WorldBuilder`.
+    # `Behaviour::World` supplies the settings lookups; this class holds the declared data.
     class World
       include Hecks::IR
       include Behaviour::World

data/lib/hecks/bluebook/lifecycle.rb

@@ -2,10 +2,8 @@ require_relative "behaviour/lifecycle"
 
 module Hecks
   module Bluebook
-    # One declared `transition` row — the state a command moves an
-    # aggregate or entity to, and, when guarded, the state(s) it must
-    # currently be in (`from:`) for the transition to apply. An unguarded
-    # transition (`from: nil`) applies from any current state.
+    # One declared `transition` row: the target state, and optionally the `from:` state(s) it needs.
+    # An unguarded transition (`from: nil`) applies from any state.
     class StateTransition
       attr_reader :target, :from
 
@@ -21,18 +19,11 @@ module Hecks
                   end
       end
 
-      # Says whether this transition is guarded to specific source states.
-      #
-      # @return [Boolean] whether this transition is guarded to specific source states,
-      #   rather than applying from any current state
       def constrained? = !@from.nil?
     end
 
-    # The built form of a `lifecycle :field, default: ... do ... end`
-    # block, produced by `DSL::LifecycleBuilder` — the field a state
-    # machine lives on, its starting value, and the declared transition
-    # table. `Behaviour::Lifecycle` supplies the reads (`states`,
-    # `target_for`, ...) built purely from this data.
+    # The built form of a `lifecycle :field, default: ... do ... end` block.
+    # Reads (`states`, `target_for`, ...) come from `Behaviour::Lifecycle`.
     class Lifecycle
       include Hecks::IR
       include Behaviour::Lifecycle
@@ -40,9 +31,7 @@ module Hecks
       emits_ir(
         field:       -> { field.to_s },
         default:     :default,
-        # `expand` is private; a Proc runs in the construct's own
-        # context, so declared emission reaches it exactly as the
-        # hand-written to_h did.
+        # `expand` is private; a Proc runs in the construct's own context, so it can reach it.
         transitions: -> { transitions.flat_map { |command, t| expand(command, t) } }
       )
 

data/lib/hecks/bluebook/meta_validator/adapter_judge.rb

@@ -1,13 +1,7 @@
 module Hecks
   module Bluebook
     module MetaValidator
-      # Offers a built .adapter to the language that describes adapters.
-      #
-      # A sibling of a bluebook again, the same shape PortJudge already is
-      # one level over — its own file, its own door, judged through its
-      # own self-hosted language (adapter.bluebook) rather than left as a
-      # plain Ruby struct nothing checks. Whole-project table-unification
-      # survey, item #13's remaining builders.
+      # Offers a built .adapter to the self-hosted adapter language (adapter.bluebook).
       class AdapterJudge
         attr_reader :refusals