hecks 1.3.0 → 1.5.0

data/lib/hecks/behaviors/dsl.rb

@@ -16,6 +16,7 @@ module Hecks
     # `validate_expect!` (private, below) is where a malformed or empty
     # `expect` is refused at build time rather than silently passing later.
     class TestCaseBuilder
+      # @param description [String] the `test "description" do ... end` text
       def initialize(description)
         @description   = description
         @tests_command = nil
@@ -26,19 +27,46 @@ module Hecks
         @expect        = {}
       end
 
+      # Records which command or query this test exercises.
+      #
+      # @param command [String, Symbol] the command or query verb, bare or dotted FQN
+      # @param on [String, Symbol, nil] the aggregate `command` is dispatched on, when
+      #   `command` is not already a dotted FQN
+      # @param kind [Symbol] `:command` or `:query`
+      # @return [void]
       def tests(command, on: nil, kind: :command)
         @tests_command = command
         @on_aggregate  = on
         @kind          = kind
       end
 
+      # Records one setup command to dispatch before the test itself runs.
+      #
+      # @param command [String, Symbol] the setup command's verb
+      # @param kwargs [Hash{Symbol => Object}] the setup command's own arguments
+      # @return [void]
       def setup(command, **kwargs)
         @setups << TestSetup.new(command: command, args: kwargs)
       end
 
+      # Merges fields into the arguments the tested command or query is called with.
+      #
+      # @param kwargs [Hash{Symbol => Object}] argument names and values to merge in
+      # @return [Hash{Symbol => Object}] the input Hash so far
       def input(**kwargs)  = @input.merge!(kwargs)
+
+      # Merges fields into what this test expects of the tested dispatch.
+      #
+      # @param kwargs [Hash{Symbol => Object}] expectation keys (`ok:`, `refused:`,
+      #   `emits:`, `count:`, or a field name) and their expected values
+      # @return [Hash{Symbol => Object}] the expectation Hash so far
       def expect(**kwargs) = @expect.merge!(kwargs)
 
+      # Builds the `TestCase` this builder collected.
+      #
+      # @return [TestCase] the built test case
+      # @raise [Malformed] if `tests` was never called, `expect` is empty, or
+      #   `expect` declares `count:` on a command or `emits:` on a query
       def build
         unless @tests_command
           raise Malformed, "test #{@description.inspect} never calls `tests` — " \
@@ -59,7 +87,7 @@ module Hecks
       # nothing and passes whenever dispatch doesn't raise; `count:` on a
       # command and `emits:` on a query are each read by neither runner
       # (Expectations#run_command/#run_query), so they're accepted here
-      # and then silently ignored at run time. Checking both at BUILD
+      # and then silently ignored at run time. Checking both at build
       # time, not in the runners, makes them errors on the file that
       # wrote them rather than green checks nobody questions.
       def validate_expect!
@@ -84,6 +112,8 @@ module Hecks
     # `vision`/`loads`/`test` calls and builds a `BehaviorsSuite` (ir.rb),
     # refusing to build one missing either `vision` or `loads` (`#build`).
     class BehaviorsBuilder
+      # @param name [String] the suite's declared name
+      # @param source_path [String] the `.behaviors` file's own path
       def initialize(name, source_path:)
         @name        = name
         @source_path = source_path
@@ -93,21 +123,40 @@ module Hecks
         @tests       = []
       end
 
+      # Records the suite's one-line description of what it is examples of.
+      #
+      # @param text [String] the vision text
+      # @return [String] `text`, unchanged
       def vision(text) = @vision = text
 
-      # Relative to THIS `.behaviors` file, never to the filesystem's cwd
+      # Relative to this `.behaviors` file, never to the filesystem's cwd
       # or a same-stem convention — scope is a fact this file declares,
       # not one a runner infers.
+      #
+      # @param paths [Array<String>] paths to the files this suite's domain boots
+      #   from, relative to the `.behaviors` file
+      # @return [void]
       def loads(*paths)
         @loads = paths.map { |path| File.expand_path(path, @source_dir) }
       end
 
+      # Builds and records one test case.
+      #
+      # @param description [String] the test's own description
+      # @yield the test's body, evaluated against a `TestCaseBuilder`
+      # @return [void]
+      # @raise [Malformed] if the test never calls `tests`, has no `expect`, or
+      #   declares `count:` on a command or `emits:` on a query
       def test(description, &block)
         builder = TestCaseBuilder.new(description)
         builder.instance_eval(&block) if block
         @tests << builder.build
       end
 
+      # Builds the `BehaviorsSuite` this builder collected.
+      #
+      # @return [BehaviorsSuite] the built suite
+      # @raise [Malformed] if the suite declares no `vision` or no `loads`
       def build
         unless @vision
           raise Malformed, "#{@source_path}: no `vision \"...\"` — say in one line " \
@@ -122,6 +171,15 @@ module Hecks
                            tests: @tests, path: @source_path)
       end
 
+      # Builds a suite in one call: constructs a builder, evaluates `block`
+      # against it, and builds the result.
+      #
+      # @param name [String] the suite's declared name
+      # @param source_path [String] the `.behaviors` file's own path
+      # @yield the suite's body, evaluated against the new builder
+      # @return [BehaviorsSuite] the built suite
+      # @raise [Malformed] if the suite declares no `vision` or `loads`, or any of
+      #   its `test` blocks is malformed
       def self.build(name, source_path:, &block)
         builder = new(name, source_path: source_path)
         builder.instance_eval(&block) if block

data/lib/hecks/behaviors/expectations.rb

@@ -7,6 +7,8 @@ require_relative "../ports/persistence/binding_policy"
 
 # Hecks::Behaviors::Expectations
 #
+# ## What it does
+#
 # One test case, start to finish: take the suite's own runtime (booted
 # once for exactly what its `loads` names, reset to nothing between
 # tests — `runtime_for`), replay `setup` dispatches, dispatch (or query)
@@ -14,20 +16,22 @@ require_relative "../ports/persistence/binding_policy"
 # runner.rb the same way the file-count/sweep concern is split from a
 # single test's own execution.
 #
-# TWO DELIBERATE DEVIATIONS from a prior port of this same idea (read
+# ## Deviations from a prior port
+#
+# Two deliberate deviations from a prior port of this same idea (read
 # before writing this, not reinvented):
 #
 # 1. A `setup` refusal and a refusal from the command under test are
-#    caught in SEPARATE rescue scopes. The prior port wrapped the whole
+#    caught in separate rescue scopes. The prior port wrapped the whole
 #    test body — setups included — in one `rescue *REFUSAL_CLASSES`, so a
 #    broken setup could spuriously satisfy `expect refused: "..."` if its
 #    own refusal happened to match the expected substring. Here, any
-#    domain refusal during `setup` is unconditionally an ERROR — the
+#    domain refusal during `setup` is unconditionally an error — the
 #    example never got to the situation it claims to test.
 #
-# 2. `emits:` is read off a `registry.event_log` DIFF around the tested
+# 2. `emits:` is read off a `registry.event_log` diff around the tested
 #    dispatch, not off `Result#events` alone. `Result#events` only holds
-#    the events the OUTERMOST dispatch announced; a policy's own cascade
+#    the events the outermost dispatch announced; a policy's own cascade
 #    reenters through the same `Dispatcher#dispatch` (`PolicyInterpreter
 #    #deliver` → `door.reenter` → `dispatch`), and every dispatch's
 #    events — outer and reentrant alike — land in the one shared
@@ -46,6 +50,15 @@ module Hecks
       REFUSAL_CLASSES = Hecks::Runtime::DOMAIN_REFUSALS
       SPECIAL_KEYS = %i[ok refused emits count].freeze
 
+      # Runs one test case: replays its `setup` dispatches, dispatches (or queries)
+      # the command under test, and checks its `expect`.
+      #
+      # @param test [Behaviors::TestCase] the test case to run
+      # @param suite [Behaviors::BehaviorsSuite] the suite `test` belongs to
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher, nil] an
+      #   already-booted runtime to reuse and reset; nil boots (or reuses the cached
+      #   boot of) `suite.loads` via `runtime_for`
+      # @return [Result] the test's pass, fail, or error outcome
       def run_one(test, suite, runtime: nil)
         runtime ||= runtime_for(suite)
         runtime.registry.reset_runtime_state!
@@ -66,18 +79,18 @@ module Hecks
         error_result(test, "#{e.class}: #{e.message}")
       end
 
-      # ONE BOOT PER SUITE, NOT PER TEST. The isolation a test needs is a
+      # One boot per suite, not per test. The isolation a test needs is a
       # runtime with nothing in it — and a boot of the same files gives
       # exactly that back for the price of `Registry#reset_runtime_state!`
       # instead of ~2s of loading, verifying and era-checking the same
       # bluebook again (chess: 76 behaviours, 155s of which was booting
-      # `chess.bluebook` 76 times). Keyed by the suite's own `loads` AND
+      # `chess.bluebook` 76 times). Keyed by the suite's own `loads` and
       # their mtimes, so an edited bluebook boots fresh on the next test
       # rather than running against a stale one — the property a watch
       # loop or a long rspec session actually relies on. `runtime:` lets
       # a caller that already holds a booted runtime (a spec, a REPL)
       # hand it in; it is reset the same way.
-      # NOT frozen — a real cache, mutated below (`RUNTIMES[key] ||=
+      # Not frozen — a real cache, mutated below (`RUNTIMES[key] ||=
       # boot_and_guard(files)`) and by #reset!. False positive for
       # Style/MutableConstant.
       # rubocop:disable-next Style/MutableConstant
@@ -85,6 +98,14 @@ module Hecks
       RUNTIMES_LOCK = Mutex.new
       private_constant :RUNTIMES, :RUNTIMES_LOCK
 
+      # Boots (or reuses the cached boot of) the runtime a suite's `loads` names.
+      #
+      # @param suite [Behaviors::BehaviorsSuite] the suite whose `loads` files boot
+      #   the runtime
+      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the cached or
+      #   freshly booted, Memory-only-guarded runtime
+      # @raise [Malformed] if any aggregate the suite boots is not bound to the
+      #   default (Memory) adapter
       def runtime_for(suite)
         files = Array(suite.loads).map { |path| File.expand_path(path) }
         key   = files.map { |file| [file, File.exist?(file) ? File.mtime(file).to_f : nil] }
@@ -94,22 +115,35 @@ module Hecks
         end
       end
 
-      # `reset_runtime_state!` only drops repository OBJECTS between
+      # `reset_runtime_state!` only drops repository objects between
       # tests (registry.rb) — sufficient isolation for `Memory`, whose
       # `@records` is a plain per-instance ivar, so a fresh object really
       # is a fresh store. Against anything else (Sqlite, Postgres) the
       # rows themselves stay put: tests leak into each other, and a
-      # suite booted against a domain's REAL hecksagon writes to a real
+      # suite booted against a domain's real hecksagon writes to a real
       # database. Refusing that wiring here, at boot, is the same shape
       # of guard `BindingPolicy` already applies to a missing bind — the
       # project's identity is refusing bad wiring up front, not
       # discovering it mid-suite.
+      #
+      # @param files [Array<String>] absolute paths to the bluebook/hecksagon/world
+      #   files to boot
+      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted,
+      #   Memory-only-guarded runtime
+      # @raise [Malformed] if any aggregate is bound to a non-Memory adapter
       def boot_and_guard(files)
         runtime = Hecks::Runtime::Loader.boot_files(files, install_facade: false)
         guard_memory_only!(runtime)
         runtime
       end
 
+      # Refuses a runtime where any aggregate is bound to anything other than the
+      # default (Memory) adapter, so tests can never leak state or touch a real store.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+      #   runtime to check
+      # @return [void]
+      # @raise [Malformed] if any aggregate is bound to a non-Memory adapter
       def guard_memory_only!(runtime)
         runtime.registry.bluebooks.each_value do |bluebook|
           bluebook.aggregates.each do |aggregate|
@@ -127,6 +161,15 @@ module Hecks
         end
       end
 
+      # Qualifies and dispatches (or queries) the command under test, catching a
+      # domain refusal as the test's own outcome rather than an error.
+      #
+      # @param test [Behaviors::TestCase] the test case to run
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      #   booted runtime
+      # @param bluebooks [Array<Bluebook::Chapter>] every chapter the suite booted,
+      #   searched to qualify a bare command/query name
+      # @return [Result] the test's pass, fail, or error outcome
       def run_tested(test, runtime, bluebooks)
         verb = qualify(test.tests_command, test.on_aggregate, bluebooks, kind: test.kind)
 
@@ -139,6 +182,13 @@ module Hecks
         check_refusal(test, e)
       end
 
+      # Dispatches the command under test and checks its `expect`.
+      #
+      # @param test [Behaviors::TestCase] the test case to run
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      #   booted runtime
+      # @param verb [String] the command's dotted FQN
+      # @return [Result] the test's pass or fail outcome
       def run_command(test, runtime, verb)
         before = runtime.registry.event_log.length
         result = dispatch_command(runtime, verb, test.input)
@@ -159,17 +209,26 @@ module Hecks
         check_ok(test) || check_fields(test, settled_state(runtime, verb, result)) || pass_result(test)
       end
 
-      # A field expectation reads the aggregate AS IT STANDS once the
+      # A field expectation reads the aggregate as it stands once the
       # dispatch and its whole cascade have run — the same "cascades are
       # always on" reading `emits:` already commits to. `Result#state` is
-      # the wrong source for that: it snapshots the instance the OUTER
+      # the wrong source for that: it snapshots the instance the outer
       # dispatch saved, and a policy's own reentrant dispatch (a ply
       # advancing off a Moved event, a move count bumping) hydrates and
-      # saves a FRESH record afterward — so a field the cascade wrote
+      # saves a fresh record afterward — so a field the cascade wrote
       # read back stale (found live: `expect move_count: 1` got 0 while
       # `emits:` saw MoveCountBumped in the same test). The repository
       # holds the settled record; read it back by the id the dispatch
       # itself answered with.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      #   booted runtime
+      # @param verb [String] the dispatched command's dotted FQN
+      # @param result [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result]
+      #   the dispatch's own result
+      # @return [Hash{Symbol => Object}] the settled record's current state, read
+      #   back from the repository; `result.state` (or `{}`) when the result has no
+      #   id or the repository no longer has that aggregate/record
       def settled_state(runtime, verb, result)
         return result.state || {} unless result.respond_to?(:id) && result.id
 
@@ -185,7 +244,7 @@ module Hecks
       # A behaviors test writes a dispatch the way the guide's own chess
       # examples do — receiver identity and command facts side by side
       # (`label: "g", id: "wn", to: { file: 2, rank: 2 }`) — and since
-      # #335 the dispatcher's own `to:` keyword is the ROUTING envelope,
+      # #335 the dispatcher's own `to:` keyword is the routing envelope,
       # so forwarding those kwargs loose collides the moment a domain
       # declares a command fact named `to` (chess does: every Move's own
       # destination). Found live: every such test failed with "to: does
@@ -202,15 +261,26 @@ module Hecks
       # expects a command's own declared attributes at the top level,
       # not a port operation's already-wrapped `to:`/`with:` shape.
       #
-      # THIS USED TO RELY ON `resolve_target` RAISING `UnknownVerb` for
-      # any port-operation verb — true only so long as nothing else ever
-      # asked it to resolve one. Now that a `policy` can legitimately
-      # `trigger` a port operation (`ReactionInvocation#resolve_target`'s
-      # own port-operation branch), that raise is gone, so this checks
-      # for a port operation directly instead of leaning on a refusal
-      # that no longer happens.
+      # Checks for a port operation directly rather than leaning on
+      # `resolve_target` to raise `UnknownVerb` for one — a refusal that held
+      # only so long as nothing else ever asked it to resolve a port-operation
+      # verb. Now that a `policy` can legitimately `trigger` a port operation
+      # (`ReactionInvocation#resolve_target`'s own port-operation branch),
+      # that raise no longer happens, so this checks directly instead.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      #   booted runtime
+      # @param verb [String] the command's dotted FQN, or a port operation's
+      # @param args [Hash{Symbol => Object}] the command's (or setup's) facts, mixing
+      #   receiver identity and declared arguments
+      # @return [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the
+      #   dispatch's own result
+      # @raise [Runtime::UnknownVerb] if `verb` is not fully qualified or names an
+      #   undeclared domain, aggregate, command, entity or port operation
+      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when the
+      #   domain refuses the call
       def dispatch_command(runtime, verb, args)
-        return runtime.dispatch(verb, **args) if port_operation?(runtime, verb)
+        return runtime.dispatch_flat(verb, args) if port_operation?(runtime, verb)
 
         invocation = begin
           Runtime::ReactionInvocation.build(registry: runtime.registry, verb: verb,
@@ -218,7 +288,7 @@ module Hecks
         rescue Runtime::UnknownVerb
           nil
         end
-        return runtime.dispatch(verb, **args) unless invocation
+        return runtime.dispatch_flat(verb, args) unless invocation
 
         if invocation.key?(:to)
           runtime.dispatch(verb, to: invocation[:to], with: invocation[:with])
@@ -227,10 +297,15 @@ module Hecks
         end
       end
 
-      # THE SAME "Head.Rest" SHAPE `Dispatcher#dispatch` AND
-      # `ReactionInvocation#resolve_target` BOTH ALREADY CHECK — a bare
+      # The same "Head.Rest" shape `Dispatcher#dispatch` and
+      # `ReactionInvocation#resolve_target` both already check — a bare
       # domain/aggregate lookup plus a port-name lookup, no command
       # resolution needed since all this asks is whether one exists.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      #   booted runtime
+      # @param verb [String] the verb to check, dotted FQN shaped
+      # @return [Boolean] true if `verb` names a port operation on a declared aggregate
       def port_operation?(runtime, verb)
         domain, aggregate_name, command_path = Naming.split_verb(verb)
         return false unless command_path
@@ -242,6 +317,13 @@ module Hecks
         rest && !!aggregate.port(head)
       end
 
+      # Runs the query under test and checks its `expect`.
+      #
+      # @param test [Behaviors::TestCase] the test case to run
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      #   booted runtime
+      # @param verb [String] the query's dotted FQN
+      # @return [Result] the test's pass or fail outcome
       def run_query(test, runtime, verb)
         rows = runtime.query(verb, **test.input)
 
@@ -267,6 +349,11 @@ module Hecks
         check_ok(test) || check_fields(test, row) || pass_result(test)
       end
 
+      # Whether `test.expect` names a field, not just one of the special keys.
+      #
+      # @param test [Behaviors::TestCase] the test case to check
+      # @return [Boolean] true if `test.expect` has any key besides `ok`, `refused`,
+      #   `emits` or `count`
       def field_expectations?(test)
         test.expect.keys.any? { |key| !SPECIAL_KEYS.include?(key) }
       end
@@ -277,6 +364,11 @@ module Hecks
       # ambiguous about which row it's describing. `check_fields` itself
       # stays row-shaped (it already is, for `run_command`'s settled
       # state); this picks which row it reads.
+      #
+      # @param test [Behaviors::TestCase] the test case, for the fail message
+      # @param rows [Array<Hash>, Hash] the query's own result
+      # @return [Hash, Result] `rows` itself when it isn't an Array; its one row when
+      #   it holds exactly one; otherwise a `fail_result` naming the row count
       def query_row(test, rows)
         return rows unless rows.is_a?(Array)
 
@@ -288,6 +380,11 @@ module Hecks
         end
       end
 
+      # Checks an `expect ok: true` expectation.
+      #
+      # @param test [Behaviors::TestCase] the test case to check
+      # @return [Result, nil] nil if `test.expect` has no `ok` key or expects `true`;
+      #   a `fail_result` if it names anything else
       def check_ok(test)
         return unless test.expect.key?(:ok)
 
@@ -297,6 +394,13 @@ module Hecks
         fail_result(test, "expect ok: only accepts true — got #{expected.inspect}")
       end
 
+      # Checks every field-name expectation in `test.expect` against `state`.
+      #
+      # @param test [Behaviors::TestCase] the test case to check
+      # @param state [Hash{Symbol, String => Object}] the settled record's (or query
+      #   row's) fields
+      # @return [Result, nil] nil if every expected field matches; a `fail_result` for
+      #   the first field that names none of `state`'s keys or doesn't match
       def check_fields(test, state)
         test.expect.each do |key, expected|
           next if SPECIAL_KEYS.include?(key)
@@ -314,6 +418,12 @@ module Hecks
         nil
       end
 
+      # Checks a caught domain refusal against `test.expect[:refused]`.
+      #
+      # @param test [Behaviors::TestCase] the test case to check
+      # @param error [StandardError] the caught refusal, a member of `REFUSAL_CLASSES`
+      # @return [Result] a `pass_result` if `test` expected this refusal's message, an
+      #   `error_result` if it expected none, or a `fail_result` if the message doesn't match
       def check_refusal(test, error)
         expected = test.expect[:refused]
         return error_result(test, "unexpected refusal (#{error.class}): #{error.message}") unless expected
@@ -331,8 +441,13 @@ module Hecks
       # `expect` values both ways — bare (`expect kind: "bishop"`) and
       # wrapped (`expect kind: { value: "bishop" }`). A live record's
       # field always comes back as a `Hecks::Runtime::Value`;
-      # normalizing BOTH sides to the same bare-scalar-or-plain-hash
+      # normalizing both sides to the same bare-scalar-or-plain-hash
       # shape is the one comparison that accepts either spelling.
+      #
+      # @param value [Object] a stored field's value, or an `expect` value to compare
+      #   it against
+      # @return [Object] the bare underlying value: unwrapped from a `Runtime::Value`,
+      #   or from a `{value: ...}` Hash; unchanged otherwise
       def normalize(value)
         return Hecks::Runtime::Value.materialize_unwrapped(value) if value.is_a?(Hecks::Runtime::Value)
         return normalize(value[:value]) if value.is_a?(Hash) && value.keys == [:value]
@@ -344,9 +459,18 @@ module Hecks
       # can name more than one bluebook, so resolution searches every
       # aggregate across every bluebook the suite booted for the one that
       # actually declares the command. `on:` (when given, only ever on
-      # the TESTED command — `setup` never receives it, see the DSL
+      # the tested command — `setup` never receives it, see the DSL
       # contract) narrows the search to one aggregate by name instead of
       # searching all of them.
+      #
+      # @param command [String, Symbol] a bare verb, or an already-dotted FQN
+      # @param on_aggregate [String, Symbol, nil] the aggregate to search, or nil to
+      #   search every aggregate of every bluebook
+      # @param bluebooks [Array<Bluebook::Chapter>] every chapter the suite booted
+      # @param kind [Symbol] `:command` or `:query`
+      # @return [String] `command` unchanged if already dotted, otherwise its resolved
+      #   dotted FQN
+      # @raise [ArgumentError] if no aggregate declares `command`, or more than one does
       def qualify(command, on_aggregate, bluebooks, kind:)
         return command.to_s if command.to_s.include?(".")
 
@@ -354,9 +478,19 @@ module Hecks
         disambiguate_qualified_name(candidates, command, kind, bluebooks)
       end
 
-      # THE SEARCH — every (bluebook, aggregate) pair that declares a
+      # Finds every aggregate that could be what a bare command/query name refers to.
+      #
+      # **The search** — every (bluebook, aggregate) pair that declares a
       # command/query named `command`, narrowed to `on_aggregate` by name
       # when given.
+      #
+      # @param command [String, Symbol] the bare verb to search for
+      # @param on_aggregate [String, Symbol, nil] the aggregate to search, or nil to
+      #   search every aggregate of every bluebook
+      # @param bluebooks [Array<Bluebook::Chapter>] every chapter the suite booted
+      # @param kind [Symbol] `:command` or `:query`
+      # @return [Array<Array(Bluebook::Chapter, Bluebook::Aggregate)>] every matching
+      #   (chapter, aggregate) pair
       def qualify_candidates(command, on_aggregate, bluebooks, kind)
         members = kind == :query ? :queries : :commands
         pairs =
@@ -368,9 +502,20 @@ module Hecks
         pairs.select { |_, agg| agg.public_send(members).any? { |m| m.hecks_name == command.to_s } }
       end
 
-      # THE REPORT — zero candidates and more-than-one candidates both
+      # Resolves a search's candidates to exactly one dotted FQN, or refuses.
+      #
+      # **The report** — zero candidates and more-than-one candidates both
       # refuse (with a different message); exactly one resolves to its
       # dotted FQN.
+      #
+      # @param candidates [Array<Array(Bluebook::Chapter, Bluebook::Aggregate)>] the
+      #   matching (chapter, aggregate) pairs found by `qualify_candidates`
+      # @param command [String, Symbol] the bare verb that was searched for
+      # @param kind [Symbol] `:command` or `:query`, for the refusal message
+      # @param bluebooks [Array<Bluebook::Chapter>] every chapter the suite booted,
+      #   for the refusal message
+      # @return [String] the one candidate's dotted FQN
+      # @raise [ArgumentError] if `candidates` is empty, or holds more than one
       def disambiguate_qualified_name(candidates, command, kind, bluebooks)
         case candidates.size
         when 0
@@ -386,8 +531,24 @@ module Hecks
         end
       end
 
+      # Builds a passing result.
+      #
+      # @param test [Behaviors::TestCase] the test that passed
+      # @return [Result] a `:pass` result
       def pass_result(test) = Result.new(description: test.description, status: :pass, message: nil)
+
+      # Builds a failing result.
+      #
+      # @param test [Behaviors::TestCase] the test whose expectation was not met
+      # @param message [String] what was expected versus what happened
+      # @return [Result] a `:fail` result
       def fail_result(test, message)  = Result.new(description: test.description, status: :fail, message: message)
+
+      # Builds an errored result.
+      #
+      # @param test [Behaviors::TestCase] the test that could not run to a conclusion
+      # @param message [String] what went wrong
+      # @return [Result] an `:error` result
       def error_result(test, message) = Result.new(description: test.description, status: :error, message: message)
 
       Result = Struct.new(:description, :status, :message, keyword_init: true)

data/lib/hecks/behaviors/ir.rb

@@ -2,24 +2,35 @@
 #
 # The `.behaviors` authoring surface's own IR — plain Structs, holding
 # exactly what `Hecks.behaviors "Name" do ... end` collected. Deliberately
-# NOT part of `Hecks::IR`/`emits_ir` — a behaviors suite is never
+# not part of `Hecks::IR`/`emits_ir` — a behaviors suite is never
 # collected into a domain Registry (see `Hecks.behaviors`), never
 # dispatched through MetaValidator, and carries none of the self-hosted
 # round-trip machinery a real bluebook construct does. It is a test
 # artifact a runner reads on demand, not a domain a boot needs.
 module Hecks
+  # The `.behaviors` toolkit: the DSL a `.behaviors` file is written against
+  # (`Hecks.behaviors`, dsl.rb), the plain-Struct IR it builds (this file), the runner
+  # that boots a suite's domain and checks each test (runner.rb, expectations.rb), and
+  # an rspec shim for a consuming app's own suite (rspec.rb).
   module Behaviors
     TestSetup = Struct.new(:command, :args, keyword_init: true)
 
     TestCase = Struct.new(:description, :tests_command, :on_aggregate, :kind,
                           :setups, :input, :expect, keyword_init: true) do
+      # Tells whether `tests_command` is already a fully qualified verb name.
+      #
       # An already-dotted tests_command is a literal FQN; otherwise `on:`
       # composes with the domain name resolved once setups/the tested
       # dispatch actually run (see Expectations — the domain isn't known
       # until `loads` is booted, so it's a runtime concern, not a field
       # here).
+      #
+      # @return [Boolean] true when `tests_command` contains a `.`
       def dotted? = tests_command.to_s.include?(".")
 
+      # Tells whether this test case exercises a query rather than a command.
+      #
+      # @return [Boolean] true when `kind` is `:query`
       def query? = kind == :query
     end
 

data/lib/hecks/behaviors/rspec.rb

@@ -4,7 +4,7 @@ require_relative "../behaviors"
 # `bundle exec rspec` uses to run `.behaviors` files as ordinary examples,
 # one `it` per test, named by the test's own description string. Same
 # shape `spec/guides_spec.rb` uses for doctested guides: the file is
-# PARSED at collection time (cheap — `Behaviors.parse`, no test actually
+# parsed at collection time (cheap — `Behaviors.parse`, no test actually
 # run yet, just enough to know the `it` names), and each test's own
 # `Expectations.run_one` runs lazily inside its own `it`, exactly when
 # rspec actually executes it.
@@ -21,6 +21,14 @@ module Hecks
     module RSpec
       module_function
 
+      # Parses one `.behaviors` file and registers an rspec example group for it, one
+      # `it` per test named by the test's own description.
+      #
+      # @param path [String] the `.behaviors` file's path
+      # @return [void]
+      # @raise [RuntimeError] not raised by this call itself; wraps `parsed.parse_error`'s
+      #   message and is raised only when rspec later runs the generated "loads without a
+      #   parse error" example, so it surfaces as that example's failure
       def describe_file(path)
         parsed = Behaviors.parse(path)