hecks 1.3.0 → 1.5.0

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

@@ -11,6 +11,14 @@ module Hecks
         class << self
           attr_accessor :resolver
 
+          # Installs a resolver for the duration of a block, restoring the earlier one afterwards
+          # even if the block raises.
+          #
+          # @param resolver [#call] called with the missing constant's name as a Symbol; whatever
+          #   it returns is what the bare constant evaluates to
+          # @yield the DSL code whose undeclared constants the resolver should answer
+          # @yieldreturn [Object] any value; it becomes this method's result
+          # @return [Object] whatever the block returns
           def with(resolver)
             previous  = @resolver
             @resolver = resolver
@@ -19,45 +27,63 @@ module Hecks
             @resolver = previous
           end
 
+          # Reports whether a resolver is installed, meaning code is running inside a DSL block.
+          #
+          # @return [Boolean] true inside a `with` block, or after `resolver=` set one directly
           def active? = !@resolver.nil?
         end
 
-        # THE SCOPED-CONSTANT BRIDGE (ADR 0025, docs/dsl-work-slices.md's
+        # The scoped-constant bridge (ADR 0025, docs/dsl-work-slices.md's
         # S0b) — a Symbol cannot answer `::`, so `Account::Debit` and
         # `admits: Account::LedgerDirection` could never resolve past
-        # their FIRST segment while `Account` returned a bare Symbol
+        # their first segment while `Account` returned a bare Symbol
         # (`resolver = ->(const) { const }`, bluebook_builder.rb's own
-        # comment on why that was right for a BARE name): Ruby's `::`
+        # comment on why that was right for a bare name): Ruby's `::`
         # operator raises `TypeError` on the returned value before any
         # DSL code runs at all, unless that value is itself a Module.
         #
-        # A REAL `Module` subclass, not a decorated Symbol, for exactly
-        # that reason — nothing else answers `::`. Every existing
-        # consumer keeps working duck-typed, not because nothing
-        # changed: `Attribute#spell`'s `type.is_a?(Module)` branch now
-        # fires where it used to fall to `type.to_s`, and
-        # `Naming.demodulise` (`path.split("::").last`) gives the
-        # IDENTICAL string either way for a single segment — the two
-        # branches were already equivalent for a name with no `::` in
-        # it, which is every bareword before this.
+        # A real `Module` subclass, not a decorated Symbol, for exactly
+        # that reason — nothing else answers `::`. Every consumer of a
+        # bareword type keeps working duck-typed: `Attribute#spell`'s
+        # `type.is_a?(Module)` branch fires for one of these where a
+        # bare Symbol falls to `type.to_s`, and `Naming.demodulise`
+        # (`path.split("::").last`) gives the identical string either
+        # way for a single segment — the two branches are equivalent
+        # for a name with no `::` in it, which is every unscoped
+        # bareword.
         class ScopedConstant < Module
+          # Wraps a constant path, the form a `ConstShim` resolver hands back for a bareword.
+          #
+          # @param path [Symbol, String] one segment such as `:Account`, or a `::`-joined path
+          # @return [Bluebook::DSL::ConstShim::ScopedConstant] a module standing in for that path
           def self.for(path) = new(path.to_s)
 
+          # @param path [String] the constant path this module stands in for
           def initialize(path)
             super()
             @path = path
           end
 
-          # ONE MORE SEGMENT, the same way an unresolved const anywhere
+          # Extends the path by one segment, so `Account::Debit` resolves past `Account`.
+          #
+          # One more segment, the same way an unresolved const anywhere
           # else does — `Account::Debit::Anything` keeps chaining rather
           # than refusing, since nothing here knows how deep a reference
           # is meant to go; the DSL keyword that finally reads `.to_s`
           # is the one place that does.
+          #
+          # @param name [Symbol] the segment written after `::`
+          # @return [Bluebook::DSL::ConstShim::ScopedConstant] a new constant for the longer path
           def const_missing(name) = ScopedConstant.for("#{@path}::#{name}")
 
           def to_s     = @path
           def to_sym   = @path.to_sym
           def inspect  = @path
+
+          # Exposes the raw path under a name no ordinary `Module` answers, so `==` can compare
+          # two scoped constants without going through `to_s`.
+          #
+          # @return [String] the `::`-joined path, such as `"Account::Debit"`
           def hecks_path = @path
 
           def ==(other) = other.is_a?(ScopedConstant) ? @path == other.hecks_path : @path.to_sym == other
@@ -65,15 +91,20 @@ module Hecks
           def hash = @path.hash
         end
 
-        # A SCOPED NAME IS WRITTEN AS TEXT, NOT AS A CONSTANT PATH — see the
+        # A scoped name is written as text, not as a constant path — see the
         # note on `admits:` in AttributeCollector. A resolver returning a
         # Module (so that `Vocabulary::QueryComparator` reaches a second
         # `const_missing`) was tried and cannot be made to hold : `Facade::
-        # Surface` installs EVERY aggregate name as a top-level constant, so
+        # Surface` installs every aggregate name as a top-level constant, so
         # once any facade is built, `Vocabulary` resolves to that real module
         # and never reaches this hook at all. A spelling that works only
         # before a facade exists is worse than one that always works.
         module Hook
+          # Answers an undeclared top-level constant from the active resolver, if there is one.
+          #
+          # @param name [Symbol] the missing constant's name
+          # @return [Object] whatever the active resolver returns for `name`
+          # @raise [NameError] if no resolver is installed, as Ruby raises for any unknown constant
           def const_missing(name)
             resolver = ConstShim.resolver
             resolver ? resolver.call(name) : super

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

@@ -14,21 +14,27 @@ module Hecks
 
         include WordGate
 
-        # `legacy_bare_port:` — ONLY `Hecks.port`'s own top-level method
+        # `legacy_bare_port:` — only `Hecks.port`'s own top-level method
         # (lib/hecks.rb) passes `true`. `PortBuilder#build` never refused
         # an empty build (no verb, no signal, nothing) — `Port.new(verb:
         # nil, signal: :reply)` is a real, allowed shape dsl_spec.rb's own
         # "a port" tests rely on (`signal`-only, no `verb` at all). The
-        # AGGREGATE-scoped (`BindingProxy#port`) and hecksagon-ROOT
-        # (`HecksagonBuilder#port_impl`) callers both reach this SAME
+        # aggregate-scoped (`BindingProxy#port`) and hecksagon-root
+        # (`HecksagonBuilder#port_impl`) callers both reach this same
         # class with `owner: nil` too when they're building the bare-verb
-        # shape (`port_impl`'s own root-level port can be EITHER shape,
+        # shape (`port_impl`'s own root-level port can be either shape,
         # decided only after `build` returns) — so `owner.nil?` cannot be
         # the discriminator between "old Hecks.port semantics" and "real
         # DomainPort semantics"; those two callers correctly want the
         # stricter "declares no verb and no operations" refusal `build`
         # already raises below, unchanged. Only the literal top-level
         # `.port` file caller wants the older, looser rule.
+        #
+        # @param name [String] the port's name
+        # @param owner [String, nil] name of the aggregate the port is declared on, handed to
+        #   each operation's builder; nil for a root-level or top-level port
+        # @param legacy_bare_port [Boolean] true only for `Hecks.port`: an empty body then builds
+        #   a verbless `Port` rather than being refused
         def initialize(name, owner: nil, legacy_bare_port: false)
           @name             = name
           @owner            = owner
@@ -38,40 +44,63 @@ module Hecks
           @legacy_bare_port = legacy_bare_port
         end
 
-        # WHAT THE OUTSIDE TELLS US — an external fact arriving, translated
-        # into this domain's own word for it. Spelled `operation` before it
-        # had a twin, and `operation` still works: the corpus is full of it,
-        # and renaming a word costs every chapter that uses it for no gain a
-        # reader can feel.
+        # Declares an inbound operation: a fact the outside world delivers to this domain.
+        #
+        # **What the outside tells us** — an external fact arriving, translated
+        # into this domain's own word for it. Spelled `operation` or `tells`;
+        # `operation` stays because the corpus is full of it, and renaming
+        # a word costs every chapter that uses it for no gain a reader can
+        # feel.
         #
-        # RENAMED FROM `tells` — item #13's full metaprogrammed dispatch
-        # (slice 4c). `operation`/`tells` are TWO separate Keyword rows
+        # Answers both words — item #13's full metaprogrammed dispatch
+        # (slice 4c). `operation`/`tells` are two separate Keyword rows
         # (a word admitting two forms) that both name `calls: "tells_impl"`
-        # — the routing between the two spellings now lives in the table,
+        # — the routing between the two spellings lives in the table,
         # not in a Ruby `alias`. Not bootstrap-reachable (checked
-        # directly), so no BOOTSTRAP_CALLS_FALLBACK entry needed.
+        # directly), so its `BOOTSTRAP_CALLS_FALLBACK` row is never consulted.
+        #
+        # @param name [String] the operation's name, such as `"PaymentSettled"`
+        # @param to [Symbol, String, Module, nil] the aggregate the operation routes to, written
+        #   as a bare constant; nil leaves routing to the operation's own attributes
+        # @yield the operation body (`attribute`, `emits`), evaluated against a
+        #   `PortOperationBuilder`
+        # @return [Array<Bluebook::PortOperation>] every operation declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if the body declares no `emits`, or uses `answers` or
+        #   `refuses`, which belong to an `asks`
         def tells_impl(name, to: nil, &)
           @operations << PortOperationBuilder.build(name, to: to, owner: @owner, direction: :inbound, &)
         end
 
-        # WHAT WE ASK OF THE OUTSIDE — the direction this language did not
-        # have. Before this, a domain could be CALLED by an adapter and never
-        # call one. An `asks` is dispatched like any other port operation, so
+        # Declares an outbound operation: a question this domain puts to the outside world.
+        #
+        # **What we ask of the outside** — the direction that lets a domain
+        # call an adapter, not only be called by one. An `asks` is dispatched
+        # like any other port operation, so
         # a `policy` can trigger it off an event, and it comes back as one of
         # the two events it named — which is what makes the outside world
         # something the model can reason about rather than a place exceptions
         # come from.
         #
-        # RENAMED FROM `asks` — item #13's full metaprogrammed dispatch
-        # (slice 4c), same reasoning as tells_impl above.
+        # Answers the `asks` word through the table's `calls:` column — item
+        # #13's full metaprogrammed dispatch (slice 4c), same reasoning as
+        # `tells_impl` above.
+        #
+        # @param name [String] the operation's name
+        # @param to [Symbol, String, Module, nil] the aggregate the operation routes to, written
+        #   as a bare constant; nil leaves routing to the operation's own attributes
+        # @yield the operation body (`attribute`, `answers`, `refuses`), evaluated against a
+        #   `PortOperationBuilder`
+        # @return [Array<Bluebook::PortOperation>] every operation declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if the body declares `emits`, or lacks either
+        #   `answers` or `refuses`
         def asks_impl(name, to: nil, &)
           @operations << PortOperationBuilder.build(name, to: to, owner: @owner, direction: :outbound, &)
         end
 
-        # THE DRIVEN HALF OF THE SAME WORD. `operation`/`emits` translates an
+        # The driven half of the same word. `operation`/`emits` translates an
         # inbound fact into this domain's own event vocabulary — there is no
         # channel back to a caller beyond the events it emits. `verb` is the
-        # opposite direction: the domain calling OUT to a swappable adapter
+        # opposite direction: the domain calling out to a swappable adapter
         # and getting a real value back (a checkout URL, a fetched document),
         # exactly what `Hecks.port "name" do verb "x" end` already builds —
         # this is that same `Port`, reached from the same `port` call
@@ -83,9 +112,12 @@ module Hecks
         # coerce-and-assign with nothing else, now executed by
         # `GenericDispatch`.
 
+        # Names the verb aggregates call this port by, which makes it a driven `Port` rather than
+        # a `DomainPort` of operations.
+        #
         # `Hecks.port "x" do verb "y"; signal :effect end`'s own two words,
         # reachable here too — a bare-verb `DomainPortBuilder.build` falls
-        # back to the SAME `Port` object `PortBuilder` produces (`build`,
+        # back to the same `Port` object `PortBuilder` produces (`build`,
         # below), so any `.port` file can migrate to being parsed by this
         # builder with zero change to its own text, or to any caller that
         # reads `.verb`/`.signal` off the `Port` it gets back. Ordinary
@@ -93,20 +125,40 @@ module Hecks
         # header is explicit that a word answered this way never reaches
         # its `method_missing`, so no new self-hosted grammar row is
         # needed for either word under this context.
+        #
+        # @param value [String, Symbol] the verb, such as `"charged_by"`
+        # @return [String] the verb as stored
         def verb(value)   = @verb = value.to_s
+
+        # Sets whether a verb-shaped port hands a value back; one left unset signals `:reply`.
+        #
+        # @param value [Symbol, String] `:reply` when the adapter answers with a value,
+        #   `:effect` when it is called only for its effect
+        # @return [Symbol] the signal as stored
         def signal(value) = @signal = value.to_sym
 
-        # THE METHOD CONTRACT — `PortBuilder#answers`'s own twin, added
-        # here after the fact: a `.port` file migrated to parse through
-        # this builder (the repoint `lib/hecks.rb#port`'s own comment
-        # describes) can still declare one (`extraction.port`'s own
+        # Declares one method an adapter bound to a verb-shaped port must respond to.
+        #
+        # **The method contract** — `PortBuilder#answers`'s own twin: a
+        # `.port` file parsed through this builder (the repoint
+        # `lib/hecks.rb#port`'s own comment describes) can declare one
+        # (`extraction.port`'s own
         # `answers :canonical`, real, live corpus text) — this builder's
         # bare-verb fallback needs to carry it through to the same `Port`
         # object `PortBuilder` itself would have built, or the migration
         # would silently drop a method-contract check for any `.port`
         # file that uses this word.
+        #
+        # @param name [Symbol, String] the method name, such as `:canonical`
+        # @return [Array<Symbol>] every method declared so far, this one last
         def answers(name) = @answers << name.to_sym
 
+        # Assembles whichever of the two port shapes the body declared.
+        #
+        # @return [Bluebook::Port, Bluebook::DomainPort] a `Port` when the body named a `verb`
+        #   (or was empty under `legacy_bare_port:`), otherwise a `DomainPort` of its operations
+        # @raise [Bluebook::DSL::Malformed] if the body declares both a verb and operations,
+        #   declares neither without `legacy_bare_port:`, or the port language refuses the `Port`
         def build
           if @verb && !@operations.empty?
             raise Malformed,
@@ -123,6 +175,19 @@ module Hecks
           DomainPort.new(name: @name, operations: @operations)
         end
 
+        # Evaluates a `port` block against a fresh builder and returns whichever shape it declared.
+        #
+        # @param name [String] the port's name
+        # @param owner [String, nil] name of the aggregate the port is declared on, or nil for a
+        #   root-level or top-level port
+        # @param legacy_bare_port [Boolean] true only for `Hecks.port`, which lets an empty body
+        #   build a verbless `Port`
+        # @yield the port body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::Port, Bluebook::DomainPort] a verb-shaped `Port`, or a `DomainPort`
+        #   holding the declared operations
+        # @raise [Bluebook::DSL::Malformed] if the body declares both shapes, declares neither
+        #   without `legacy_bare_port:`, holds an operation its builder refuses, or uses a word
+        #   the `DomainPort` grammar does not admit
         def self.build(name, owner: nil, legacy_bare_port: false, &block)
           builder = new(name, owner: owner, legacy_bare_port: legacy_bare_port)
           builder.instance_eval(&block) if block