hecks 1.3.0 → 1.4.0

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

@@ -1,25 +1,29 @@
+require_relative "bootstrap_table"
+
 module Hecks
   module Bluebook
     module DSL
-      # ITEM #13's FULL METAPROGRAMMED DISPATCH — slices 1-2 of 4, whole-
+      # Item #13's full metaprogrammed dispatch — slices 1-2 of 4, whole-
       # project table-unification survey. WordGate (the first slice,
-      # already shipped) only CHECKS a word's admissibility; this module
-      # EXECUTES the safe, mechanical subset of what a word actually
-      # DOES, read live off the SAME self-hosted grammar table — so a
+      # already shipped) only checks a word's admissibility; this module
+      # executes the safe, mechanical subset of what a word actually
+      # does, read live off the same self-hosted grammar table — so a
       # builder method for one of these words no longer needs to be
       # hand-written at all. Called from `WordGate#method_missing`'s own
       # "admitted here, no builder method for it yet" branch, so it only
       # ever sees a word whose (context, word) pair the grammar already
       # admits.
       #
-      # SCOPE, deliberately narrow and VERIFIED word-by-word — a full
+      # ## What is covered
+      #
+      # Scope, deliberately narrow and verified word-by-word — a full
       # audit read every real Ruby builder method's own source before
       # any of this was written, not inferred from the table's shape
       # alone (which fooled a first pass: `ReadModelBuilder#group_by`/
-      # `#include` LOOK like plain fills from `kind`/`fills` alone, but
+      # `#include` look like plain fills from `kind`/`fills` alone, but
       # actually wrap their arguments in a Hash/tuple). What's covered:
       #
-      #   - a SINGLE, non-variadic, positional Argument row whose value
+      #   - a single, non-variadic, positional Argument row whose value
       #     is stored with nothing beyond a uniform, kind-driven
       #     coercion (`COERCE_BY_KIND`) — or, for `kind: "text"`, no
       #     coercion at all when the row's own `coerce: "false"` says so
@@ -27,43 +31,45 @@ module Hecks
       #     is a same-object no-op for every real corpus use, but a
       #     genuine behavior change for a direct Ruby API call passing
       #     something else)
-      #   - a scalar ASSIGN (`@ivar = value`) or list APPEND (`@ivar <<
+      #   - a scalar assign (`@ivar = value`) or list append (`@ivar <<
       #     value`), chosen by whether the ivar `fills:` names is
-      #     ALREADY an Array at call time (every candidate's own
+      #     already an Array at call time (every candidate's own
       #     `initialize` pre-populates its accumulating ivars as `[]` —
       #     read live, not assumed)
-      #   - a ZERO-ARGUMENT word, either (a) one of several sibling
-      #     Keyword rows in the SAME context sharing the SAME `fills:`
-      #     target — derives its own stored value from ITS OWN word
+      #   - a zero-argument word, either (a) one of several sibling
+      #     Keyword rows in the same context sharing the same `fills:`
+      #     target — derives its own stored value from its own word
       #     name as a symbol (`core`/`generic`/`supporting` all fill
-      #     `classification`), or (b) the ONLY Keyword row filling its
+      #     `classification`), or (b) the only Keyword row filling its
       #     own `fills:` target — a bare marker, stores literal `true`
       #     (`ReadModel#count`)
       #   - an OPENS_BLOCK word named in `SAFE_OPENS_BLOCK` below,
-      #     verified to do NOTHING beyond "build the child, instance_
+      #     verified to do nothing beyond "build the child, instance_
       #     eval the block against it, append the result" — see that
       #     constant's own comment
       #   - (slice 2) a single-fill word whose row also names a `blank_
-      #     message:` — raises that EXACT Malformed text if the coerced
+      #     message:` — raises that exact Malformed text if the coerced
       #     value is blank, before storing it, matching a real hand-
       #     written guard exactly (`Translation#retired`/
       #     `TranslationAggregate#drop`, the only two words in the whole
       #     grammar with this precise shape — `required: "true"` alone
       #     only gates Ruby's own arity, never a present-but-blank
-      #     value, and most `required: "true"` words do NOT raise on
+      #     value, and most `required: "true"` words do not raise on
       #     blank, so this needed a real per-row signal, not an
       #     assumption from `required:` alone)
       #
-      # Explicitly OUT of this slice (found live, during the audit, not
+      # ## What stays hand-written
+      #
+      # Explicitly out of this slice (found live, during the audit, not
       # assumed) — stays hand-written, unaffected, until a later slice's
       # own new table columns (`gated_by:`/`calls:`) can name
       # what it really does: variadic accumulation with a real transform
       # (`attaches_to`); source-block extraction (`ensures`, `where`);
       # Struct/Hash-wrapping (`limit`, `group_by`, `rekey`); a guard
-      # clause NOT reducible to a plain blank-check (`role`'s own "raise
-      # if ALREADY set" uniqueness gate — a genuinely different shape
+      # clause not reducible to a plain blank-check (`role`'s own "raise
+      # if already set" uniqueness gate — a genuinely different shape
       # from `retired`/`drop`'s own blank-check, needing its own
-      # design); a dynamically-BUILT refusal message rather than one
+      # design); a dynamically-built refusal message rather than one
       # fixed string (`TranslationAggregateBuilder#unresolved` — real
       # branching logic choosing between several message shapes, not a
       # simple "always refuses" flag; belongs with `calls:`, slice 4,
@@ -74,7 +80,7 @@ module Hecks
       # `Bluebook#aggregate`, `Translation#aggregate`) or doing anything
       # beyond a bare fold after building (`Aggregate#policy`'s stamp,
       # `Aggregate#value_object`'s flatten, `Hecksagon#port`'s resolver-
-      # swap-and-branch); the DEFERRED-build queue pattern (`Aggregate`/
+      # swap-and-branch); the deferred-build queue pattern (`Aggregate`/
       # `Entity`'s own `command`/`entity`/`query`); the shadow_parsing?-
       # gated words (`has_many`/`has_one`/`belongs_to`/`then_set`/
       # `trigger`/`dispatch`/`one_of` — each delegates to its own
@@ -84,18 +90,20 @@ module Hecks
       # `File`-context word (routes through `Runtime.current_registry`,
       # a side effect this module has no business performing).
       #
-      # TWO FURTHER, DIFFERENT reasons a word can look table-safe and
+      # ## Words that look table-safe and are not
+      #
+      # Two further, different reasons a word can look table-safe and
       # still be excluded, both found live rather than assumed:
-      #   - BOOTSTRAP REACHABILITY. `WordGate`'s own gate steps aside
+      #   - Bootstrap reachability. `WordGate`'s own gate steps aside
       #     entirely while `MetaValidator.bootstrapping?` (the meta-
       #     domain's own circularity — its grammar table doesn't exist
-      #     yet to read), and `load_grammar_into` loads REAL `.port`/
-      #     `.adapter` files, plus every core `.bluebook` chapter, DURING
+      #     yet to read), and `load_grammar_into` loads real `.port`/
+      #     `.adapter` files, plus every core `.bluebook` chapter, during
       #     that exact window. Any word those files actually call (found
       #     to be nearly every common one — `vision`/`core`/`generic`/
       #     `supporting`/`description`/`goal`/`emits`/`role`/`identified_
       #     by` describe literally every self-hosted aggregate/command)
-      #     has NO working method to fall back on if its hand-written
+      #     has no working method to fall back on if its hand-written
       #     `def` is removed — `super` from `WordGate#method_missing`
       #     just raises `NoMethodError`. `PortBuilder`/`AdapterBuilder`/
       #     `BluebookBuilder` turned out to be entirely off-limits to
@@ -103,13 +111,13 @@ module Hecks
       #     booting `MetaValidator.grammar_registry` after each
       #     candidate removal, not assumed safe from reading the table
       #     alone.
-      #   - A CONFLICTING HAND-WRITTEN `method_missing`. `WorldBuilder`
-      #     and `HecksagonBuilder` each define their OWN `method_missing`
+      #   - A conflicting hand-written `method_missing`. `WorldBuilder`
+      #     and `HecksagonBuilder` each define their own `method_missing`
       #     directly on the class (for genuinely open-ended settings/
       #     collector verbs) — a method defined directly on a class always
       #     wins over one from an included module in Ruby's own method
       #     resolution, so `WordGate`'s (and this module's) own
-      #     `method_missing` never runs for THEIR builders at all. Their
+      #     `method_missing` never runs for their builders at all. Their
       #     own candidate words (`realm`/`latest`, `subscribe`) stay
       #     hand-written for this structural reason, independent of
       #     whether their own behavior would otherwise qualify.
@@ -119,10 +127,10 @@ module Hecks
         COERCE_BY_KIND = { "text" => :to_s, "symbol" => :to_sym }.freeze
 
         # (context, word) OPENS_BLOCK pairs verified, by reading every
-        # real Ruby method, to do NOTHING beyond building the child and
+        # real Ruby method, to do nothing beyond building the child and
         # appending it — see this file's own header for the full account
         # of what was excluded and why. Value: the ivar the built child
-        # is appended into. NOT derivable from `fills:` — every one of
+        # is appended into. Not derivable from `fills:` — every one of
         # these Keyword rows carries `fills: ""`; the append target is
         # implicit in the hand-written code today, never named by the
         # table at all, so this is the one place slice 1 hand-names a
@@ -134,122 +142,72 @@ module Hecks
           %w[Bluebook read_model]      => :read_models
         }.freeze
 
-        # `WordGate#method_missing`'s OWN bootstrap-window fallback,
-        # consulted ONLY while `MetaValidator.bootstrapping?` (the real
+        # `WordGate#method_missing`'s own bootstrap-window fallback,
+        # consulted only while `MetaValidator.bootstrapping?` (the real
         # table doesn't exist yet to read `keyword[:calls]` from). Names
-        # the SAME (context, word) -> method pairs the real table's own
-        # `calls:` column carries for these rows — kept in sync by hand,
-        # the one place in this whole arc that was worth it: it
-        # duplicates a METHOD NAME, never the method's own logic, so
-        # there is nothing here that could drift into a WRONG ANSWER,
-        # only (if ever forgotten) into `attribute` staying unreachable
-        # during bootstrap, the same loud `NoMethodError` failure this
-        # whole mechanism already had before slice 3 existed.
-        BOOTSTRAP_CALLS_FALLBACK = {
-          %w[Aggregate attribute]        => :attribute_impl,
-          %w[Entity attribute]           => :attribute_impl,
-          %w[Command attribute]          => :attribute_impl,
-          %w[ValueObject attribute]      => :attribute_impl,
-          %w[Query attribute]            => :attribute_impl,
-          %w[PortOperation attribute]    => :attribute_impl,
-          %w[Command role]               => :role_impl,
-          # given/invariant/reference_to — slice 4b. Each is a SEPARATE
-          # per-builder implementation (not a shared mixin like
-          # attribute_impl), so every (context, word) pair below names
-          # its OWN builder's own method, even where several share a
-          # name.
-          %w[Aggregate given]            => :given_impl,
-          %w[Entity given]               => :given_impl,
-          %w[Command given]              => :given_impl,
-          %w[Aggregate invariant]        => :invariant_impl,
-          %w[Entity invariant]           => :invariant_impl,
-          %w[ValueObject invariant]      => :invariant_impl,
-          %w[Aggregate reference_to]     => :reference_to_impl,
-          %w[Entity reference_to]        => :reference_to_impl,
-          %w[Command reference_to]       => :reference_to_impl,
-          %w[Query reference_to]         => :reference_to_impl,
-          %w[ReadModel reference_to]     => :reference_to_impl,
-          %w[PortOperation reference_to] => :reference_to_impl,
-          # `belongs_to` — genuinely NEW bootstrap-reachability, post-dating
-          # the "not bootstrap-reachable" determination above: has_many/
-          # has_one/belongs_to were retired everywhere when that check was
-          # made, so nothing core/attached used one to describe itself.
-          # Wave 6 (identity-and-relationships arc) un-deprecates all three
-          # for real, and syntax.bluebook's own Bluebook.Declare relationship
-          # (`belongs_to Bluebook`) now uses one describing itself — checked
-          # directly (only `belongs_to`, not `has_many`/`has_one`, is
-          # actually used this way by any core/attached chapter today).
-          %w[Aggregate belongs_to]       => :belongs_to_impl,
-          # slice 4c — the remaining hand-written words a fresh survey
-          # found still un-migrated across every builder. Each checked
-          # for bootstrap-reachability individually (grepped directly
-          # against every core/attached chapter, not assumed); only the
-          # ones below actually are.
-          %w[Bluebook aggregate]         => :aggregate_impl,
-          %w[Aggregate provenance]       => :provenance_impl,
-          %w[Aggregate identified_by]    => :identified_by_impl,
-          %w[Aggregate lifecycle]        => :lifecycle_impl,
-          %w[Aggregate entity]           => :entity_impl,
-          %w[Aggregate query]            => :query_impl,
-          %w[Aggregate policy]           => :policy_impl,
-          %w[Aggregate command]          => :command_impl,
-          %w[Aggregate projects]         => :projects_impl,
-          %w[Entity identified_by]       => :identified_by_impl,
-          %w[Entity command]             => :command_impl,
-          %w[Entity query]               => :query_impl,
-          %w[Entity lifecycle]           => :lifecycle_impl,
-          %w[Command provenance]         => :provenance_impl,
-          %w[Command sets]               => :sets_impl,
-          %w[Lifecycle transition]       => :transition_impl,
-          %w[ReadModel where]            => :where_impl,
-          %w[ReadModel order_by]         => :order_by_impl,
-          %w[ReadModel include]          => :include_impl,
-          %w[Query where]                => :where_impl,
-          %w[Query order_by]             => :order_by_impl,
-          %w[Entity entity]              => :entity_impl,
-          %w[ValueObject member]         => :member_impl,
-          # slice 5. `port`/`realm`/`latest` — real, closed-set words
-          # that sat unreachable behind Hecksagon/World's own class-level
-          # `method_missing` (see WordGate#word_gate_dispatch's own
-          # header), not bootstrap circularity as such, but the SAME
-          # fallback table serves them: this hash is looked up before
-          # `word_gate_dispatch` even runs, keyed by whichever context
-          # the caller's own class reports.
-          %w[Hecksagon port]             => :port_impl,
-          %w[World realm]                => :realm_impl,
-          %w[World latest]               => :latest_impl,
-          # `["Type", word]` — ONE entry each covers `list_of`/`one_of`
-          # for EVERY calling context (Aggregate/Entity/Command/Query/
-          # PortOperation/ValueObject all use them in an attribute's own
-          # type position, and `self.class::GRAMMAR_CONTEXT` can never
-          # actually equal "Type" — see `word_gate_dispatch`'s own
-          # header). The bootstrap branch checks this key directly, the
-          # same way the ordinary `word_gate_dispatch` path's own
-          # "Type"-context fallback does.
-          %w[Type list_of]               => :list_of_impl,
-          %w[Type one_of]                => :one_of_impl
-        }.freeze
+        # the same (context, word) -> method pairs the real table's own
+        # `calls:` column carries — every live row, projected ahead of
+        # time into the committed lib/hecks/bluebook/dsl/bootstrap_table.rb
+        # (bin/project_bootstrap_table, pinned by spec/bootstrap_table_spec.rb).
+        #
+        # Every row is carried, rather than a hand-kept subset checked for
+        # bootstrap-reachability by grepping the core chapters. Carrying
+        # all of them costs nothing: a builder with its own `def` never
+        # reaches `method_missing`, and one without gains the same dispatch
+        # it gets once bootstrapping ends. `["Type", word]` rows still cover
+        # `list_of`/`one_of` in an attribute's type position for every
+        # calling context (see `word_gate_dispatch`'s own header).
+        BOOTSTRAP_CALLS_FALLBACK = BootstrapTable::CALLS
 
         module_function
 
-        # THE STATIC PREDICATE — does this (context, word) pair fall
-        # within this slice's own verified scope, WITHOUT executing
+        # Reports whether `try` would execute a (context, word) pair, without executing anything.
+        #
+        # **The static predicate** — does this (context, word) pair fall
+        # within this slice's own verified scope, without executing
         # anything? The same row-shape checks `try` itself runs before
         # ever touching a real argument, shared so a conformance spec
         # (which has no real call, no real builder instance) can ask the
-        # SAME question `method_missing` answers live.
+        # same question `method_missing` answers live.
+        #
+        # @param context [String] the grammar context, a builder's `GRAMMAR_CONTEXT` such as
+        #   `"Aggregate"`, or `"Type"`
+        # @param word [String] the DSL word; a Symbol never matches a row
+        # @param rows [Hash{Symbol => Array<Hash{Symbol => String}>}] the grammar table, with
+        #   `:keywords` and `:arguments` row lists; defaults to the live self-hosted table
+        # @return [Boolean] true when `try` would execute the word rather than answer `NOT_HANDLED`
         def handles?(context, word, rows: MetaValidator::SyntaxBoot.call)
           !shape_for(context, word, rows).nil?
         end
 
+        # Executes a grammar-admitted word straight off the table when its row shape is one of
+        # the four verified safe ones.
+        #
         # `NOT_HANDLED` for anything outside this slice's own verified
         # scope — the caller (`WordGate#method_missing`) falls through
-        # to its own existing "not yet implemented" refusal, UNCHANGED,
+        # to its own existing "not yet implemented" refusal, unchanged,
         # the exact same message a word not yet migrated to any slice
         # already gets today. A real `ArgumentError` — matching what a
         # hand-written method of the same arity would raise — for a
-        # call whose SHAPE the grammar admits but whose actual argument
+        # call whose shape the grammar admits but whose actual argument
         # count doesn't match; never a silent wrong answer.
+        #
+        # @param builder [Bluebook::DSL::WordGate] the builder instance the word was called on
+        # @param context [String] the grammar context the word was admitted under
+        # @param word [String] the DSL word being executed
+        # @param args [Array<Object>] the call's positional arguments
+        # @param kwargs [Hash{Symbol => Object}] the call's keyword arguments
+        # @param block [Proc, nil] the block given to the word, if any
+        # @param rows [Hash{Symbol => Array<Hash{Symbol => String}>}] the grammar table, with
+        #   `:keywords` and `:arguments` row lists
+        # @return [Object] what executing the word produced — the target method's own result
+        #   for a `calls:` row, otherwise the stored value or the list appended to — or
+        #   `NOT_HANDLED` when the word is outside the verified scope
+        # @raise [ArgumentError] if the word is table-executed and the positional argument count
+        #   does not match what its row admits
+        # @raise [Bluebook::DSL::Malformed] if a single-fill row names a `blank_message:` and the
+        #   value is blank, or the `calls:` target itself refuses the declaration
+        # @raise [Runtime::WiringError] if `shape_for` names a kind this method has no arm for
         def try(builder, context, word, args, kwargs, block, rows)
           shape = shape_for(context, word, rows)
           return NOT_HANDLED unless shape
@@ -274,7 +232,9 @@ module Hecks
           end
         end
 
-        # THE ONE PLACE ROW SHAPE IS JUDGED — returns a small Hash naming
+        # Classifies a (context, word) pair into the table-executable shape its rows describe.
+        #
+        # The one place row shape is judged — returns a small Hash naming
         # which of the four safe shapes (context, word) is, or `nil` if
         # it falls outside this slice's own verified scope. No argument
         # values are read here; this only ever looks at the table.
@@ -284,6 +244,14 @@ module Hecks
         # checks before it. Splitting per shape would mean re-deriving or
         # threading those locals across method boundaries for a
         # classification that is only ever read top-to-bottom once, here.
+        #
+        # @param context [String] the grammar context to look the word up under
+        # @param word [String] the DSL word; retired rows never match
+        # @param rows [Hash{Symbol => Array<Hash{Symbol => String}>}] the grammar table, with
+        #   `:keywords` and `:arguments` row lists
+        # @return [Hash{Symbol => Object}, nil] `:kind` is `:calls_through` (with `:calls`, the
+        #   target method name), `:opens_block` or `:zero_arg` (with `:keyword`, the row), or
+        #   `:single_fill` (with `:fills` and `:argument`); nil when the word is out of scope
         # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def shape_for(context, word, rows)
           keyword = rows[:keywords].find { |k| k[:context] == context && k[:word] == word && k[:status] != "retired" }
@@ -309,19 +277,44 @@ module Hecks
           { kind: :single_fill, fills: fills, argument: arg }
         end
 
+        # Forwards a word's whole call to the builder method its row's `calls:` column names.
+        #
         # `keyword[:calls]` names a real Ruby method whose whole call —
         # every positional, every kwarg, the block, all of it — forwards
-        # here UNCHANGED. No argument-shape interpretation at all,
+        # here unchanged. No argument-shape interpretation at all,
         # deliberately: the target method (`AttributeCollector#
         # attribute_impl`, etc.) already does its own, real, hand-
         # written argument handling; this is a pure, transparent `send`,
         # the lowest-risk possible shape for a word whose own logic is
         # too complex to re-derive from the table (type-quoting refusal,
         # closed-set synthesis, pattern validation, ...).
+        #
+        # @param builder [Bluebook::DSL::WordGate] the builder instance to send the call to
+        # @param calls [String, Symbol] the target method's name, such as `"attribute_impl"`
+        # @param args [Array<Object>] positional arguments, forwarded unchanged
+        # @param kwargs [Hash{Symbol => Object}] keyword arguments, forwarded unchanged
+        # @param block [Proc, nil] the block, forwarded unchanged
+        # @return [Object] whatever the target method returns
+        # @raise [Bluebook::DSL::Malformed] if the target method refuses the declaration
         def try_calls_through(builder, calls, args, kwargs, block)
           builder.send(calls, *args, **kwargs, &block)
         end
 
+        # Builds a child construct from a block-opening word and appends it to the builder's list.
+        #
+        # @param builder [Bluebook::DSL::WordGate] the builder whose list receives the child
+        # @param keyword [Hash{Symbol => String}] the word's Keyword row; `:opens` names the
+        #   child builder class without its `Builder` suffix, and the pair of `:context` and
+        #   `:word` must be a `SAFE_OPENS_BLOCK` key
+        # @param args [Array<Object>] the call's positional arguments; exactly one, the child's
+        #   name
+        # @param kwargs [Hash{Symbol => Object}] the call's keyword arguments
+        # @param block [Proc, nil] the child's body, evaluated against the child builder
+        # @return [Array<Object>, Object] the builder's list with the built child appended, or
+        #   `NOT_HANDLED` when any keyword argument was given
+        # @raise [ArgumentError] if the call does not carry exactly one positional argument
+        # @raise [KeyError] if the row's context and word are not in `SAFE_OPENS_BLOCK`
+        # @raise [Bluebook::DSL::Malformed] if the child builder refuses its own body
         def try_opens_block(builder, keyword, args, kwargs, block)
           return NOT_HANDLED unless kwargs.empty?
 
@@ -337,6 +330,15 @@ module Hecks
           list << child
         end
 
+        # Stores a zero-argument word's value into the instance variable its row's `fills:` names.
+        #
+        # @param builder [Bluebook::DSL::WordGate] the builder whose instance variable is set
+        # @param keyword [Hash{Symbol => String}] the word's Keyword row, read for `:context`,
+        #   `:fills` and `:word`
+        # @param args [Array<Object>] the call's positional arguments, which must be empty
+        # @return [Symbol, true] the stored value: the word itself as a Symbol when sibling words
+        #   share the same `fills:` target (`core`/`generic`/`supporting`), otherwise `true`
+        # @raise [ArgumentError] if any positional argument was given
         def try_zero_arg(builder, keyword, args)
           raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0)" unless args.empty?
 
@@ -349,6 +351,20 @@ module Hecks
           builder.instance_variable_set(:"@#{keyword[:fills]}", value)
         end
 
+        # Coerces a word's one positional argument and stores it, appending when the target
+        # instance variable already holds an Array and assigning otherwise.
+        #
+        # @param builder [Bluebook::DSL::WordGate] the builder whose instance variable is filled
+        # @param fills [String] the instance variable's name, without the `@`
+        # @param arg [Hash{Symbol => String}] the word's single Argument row, read for `:kind`,
+        #   `:coerce` and `:blank_message`
+        # @param args [Array<Object>] the call's positional arguments; exactly one
+        # @param kwargs [Hash{Symbol => Object}] the call's keyword arguments
+        # @return [Object] the stored value, or the Array it was appended to, or `NOT_HANDLED`
+        #   when any keyword argument was given
+        # @raise [ArgumentError] if the call does not carry exactly one positional argument
+        # @raise [Bluebook::DSL::Malformed] if the row names a `blank_message:` and the coerced
+        #   value is blank
         def try_single_fill(builder, fills, arg, args, kwargs)
           return NOT_HANDLED unless kwargs.empty?