hecks 3.5.0 → 3.6.0

data/lib/hecks/behaviors/dsl.rb

@@ -77,21 +77,26 @@ module Hecks
       # Refuses expectations that would pass silently: an empty `expect`, `count:` on a command,
       # or `emits:` on a query (neither runner reads those). Checked at build time.
       def validate_expect!
-        if @expect.empty?
-          raise Malformed, "test #{@description.inspect} has no `expect` — say what this " \
-                           "example proves (ok:, refused:, emits:, count:, or a field name)"
-        end
+        problem = expect_problem
+        raise Malformed, "test #{@description.inspect}#{problem}" if problem
+      end
 
-        if @kind == :command && @expect.key?(:count)
-          raise Malformed, "test #{@description.inspect}: `expect count:` only applies to " \
-                           "queries — a command has no row count to check"
-        end
+      # @return [String, nil] what is wrong with the expectations, worded to follow the test's
+      #   description; nil when they are fine
+      def expect_problem
+        return expect_empty_problem if @expect.empty?
+        return ": `expect count:` only applies to queries — a command has no row count to check" if misplaced?(:command, :count)
 
-        if @kind == :query && @expect.key?(:emits)
-          raise Malformed, "test #{@description.inspect}: `expect emits:` only applies to " \
-                           "commands — a query never dispatches, so it never emits"
-        end
+        ": `expect emits:` only applies to commands — a query never dispatches, so it never emits" if misplaced?(:query, :emits)
       end
+
+      def expect_empty_problem
+        " has no `expect` — say what this example proves (ok:, refused:, emits:, count:, or a field name)"
+      end
+
+      # @return [Boolean] whether the test is of `kind` and expects `key`, which only the other
+      #   kind can satisfy
+      def misplaced?(kind, key) = @kind == kind && @expect.key?(key)
     end
 
     # The top-level `Hecks.behaviors` receiver; builds a `BehaviorsSuite` (ir.rb).

data/lib/hecks/behaviors/expectations/boot.rb

@@ -0,0 +1,81 @@
+require_relative "../ir"
+require_relative "../../runtime/loader"
+require_relative "../../runtime/errors"
+require_relative "../../ports/persistence/binding_policy"
+
+module Hecks
+  module Behaviors
+    module Expectations
+      # Boots the runtime a behaviors suite's `loads` names, once per set of files, and refuses
+      # one that binds an aggregate to anything but Memory. Extended onto `Expectations`.
+      module Boot
+        # Cached per suite, keyed by `loads`' file paths and mtimes, so a boot is
+        # reused across tests but an edited bluebook boots fresh on the next one.
+        # Mutated in place (`RUNTIMES[key] ||= boot_and_guard(files)`).
+        # rubocop:disable-next Style/MutableConstant
+        RUNTIMES      = {}
+        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] }
+
+          RUNTIMES_LOCK.synchronize do
+            RUNTIMES[key] ||= boot_and_guard(files)
+          end
+        end
+
+        # Refuses at boot when any aggregate binds to a non-Memory adapter —
+        # `reset_runtime_state!` only resets Memory's own per-instance store.
+        #
+        # @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_doors: 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|
+              bind = Ports::Persistence::BindingPolicy.resolve(runtime.registry, bluebook.name, aggregate)
+              next if bind.adapter == Ports::Persistence::DEFAULT_ADAPTER
+
+              raise Malformed, non_memory_message(bluebook, aggregate, bind)
+            end
+          end
+        end
+
+        # @return [String] why a behaviors suite refuses an aggregate that is not bound to Memory
+        def non_memory_message(bluebook, aggregate, bind)
+          "#{bluebook.name}::#{aggregate.hecks_name} is persisted_by " \
+            "#{bind.adapter.inspect}, not #{Ports::Persistence::DEFAULT_ADAPTER.inspect} — " \
+            "a behaviors suite's `loads` must resolve every aggregate to an in-memory " \
+            "binding, or tests leak state into each other and write to a real database. " \
+            "Load a Memory-bound sibling hecksagon instead of the domain's real one — see " \
+            "examples/pizzas/bluebook/pizzas.behaviors's own `loads` comment for the pattern."
+        end
+      end
+    end
+  end
+end

data/lib/hecks/behaviors/expectations/checks.rb

@@ -0,0 +1,178 @@
+module Hecks
+  module Behaviors
+    module Expectations
+      # The checks of a test's `expect` against what a dispatch or query settled on, and the
+      # results they build. Extended onto `Expectations`.
+      module Checks
+        # 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
+
+        # A field expectation on a query only makes sense once it has settled on
+        # exactly one row; this picks that row (or fails naming the row count).
+        #
+        # @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)
+
+          case rows.size
+          when 1 then rows.first
+          when 0 then fail_result(test, "expect names a field, but the query returned no rows")
+          else fail_result(test, "expect names a field, but the query returned #{rows.size} rows — " \
+                                 "narrow it with `input`/`expect count: 1` first")
+          end
+        end
+
+        # Fails a test that expected a refusal but whose dispatch or query went through.
+        #
+        # @param test [Behaviors::TestCase] the test case to check
+        # @param what [String] what succeeded, for the message
+        # @return [Result, nil] a `fail_result` when `test.expect` names a refusal; nil otherwise
+        def refused_but_succeeded(test, what)
+          return unless test.expect.key?(:refused)
+
+          fail_result(test, "expected refused: #{test.expect[:refused].inspect} but #{what} succeeded")
+        end
+
+        # Checks `expect emits:` against the events a dispatch appended to the log.
+        #
+        # @param before [Integer] the event log's length before the dispatch
+        # @return [Result, nil] a `fail_result` when the emitted names differ; nil otherwise
+        def unexpected_emits(test, runtime, before)
+          expected = test.expect[:emits]
+          return unless expected
+
+          actual = runtime.registry.event_log[before..].map(&:name)
+          return if actual == expected
+
+          fail_result(test, "expected emits: #{expected.inspect}, got #{actual.inspect}")
+        end
+
+        # Checks `expect count:` against what a query returned.
+        #
+        # @return [Result, nil] a `fail_result` when the row count differs; nil otherwise
+        def unexpected_count(test, rows)
+          expected = test.expect[:count]
+          return unless expected
+
+          count = row_count(rows)
+          fail_result(test, "expected count: #{expected}, got #{count}") if count != expected
+        end
+
+        # @return [Integer] how many rows a query answered: its size, or one for a single row, or
+        #   none for nil
+        def row_count(rows)
+          return rows.size if rows.is_a?(Array)
+
+          rows.nil? ? 0 : 1
+        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)
+
+          expected = test.expect[:ok]
+          return if expected == true || expected.nil?
+
+          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)
+
+            failure = field_failure(test, state, key, expected)
+            return failure if failure
+          end
+          nil
+        end
+
+        # @return [Result, nil] a `fail_result` when `state` lacks the field or holds another value
+        def field_failure(test, state, key, expected)
+          unless state.key?(key) || state.key?(key.to_s)
+            return fail_result(test, "expect #{key}: names no field on the tested aggregate — " \
+                                     "valid expect keys are ok:, refused:, emits:, count: (queries only), " \
+                                     "or a real field name")
+          end
+
+          actual = normalize(state.key?(key) ? state[key] : state[key.to_s])
+          return if actual == normalize(expected)
+
+          fail_result(test, "expected #{key}: #{expected.inspect}, got #{actual.inspect}")
+        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
+
+          msg = error.message.to_s
+          # hecks's given/ensures refusals render "Command refused —
+          # <description>" (RefusalWording) ; a behaviors file names just
+          # the description — end_with?/include? bridges the prefix.
+          return pass_result(test) if msg == expected || msg.end_with?(expected) || msg.include?(expected)
+
+          fail_result(test, "expected refused: #{expected.inspect}, got #{msg.inspect}")
+        end
+
+        # Normalizes both `expect` spellings (bare or `{value: ...}`) and a live
+        # `Hecks::Runtime::Value` field to the same bare-scalar-or-plain-hash shape.
+        #
+        # @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]
+
+          value
+        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)
+      end
+    end
+  end
+end

data/lib/hecks/behaviors/expectations/dispatching.rb

@@ -0,0 +1,93 @@
+require_relative "../../runtime/reaction_invocation"
+
+module Hecks
+  module Behaviors
+    module Expectations
+      # Sends a verb to the booted runtime, and reads back what it settled. Extended onto
+      # `Expectations`.
+      module Dispatching
+        # Reads the aggregate back from the repository, not `Result#state` — a
+        # policy's own reentrant dispatch can re-save the record afterward.
+        #
+        # @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 does not have that aggregate/record
+        def settled_state(runtime, verb, result)
+          record = settled_record(runtime, verb, result)
+          record ? record.state : (result.state || {})
+        end
+
+        # @return [Runtime::Instance, nil] the repository's record for the dispatch's id, when the
+        #   result has an id and the aggregate is declared
+        def settled_record(runtime, verb, result)
+          return unless result.respond_to?(:id) && result.id
+
+          aggregate = verb_aggregate(runtime, verb)
+          aggregate && runtime.registry.repository(verb.split("::", 2).first, aggregate).find(result.id)
+        end
+
+        # @return [Bluebook::Aggregate, nil] the aggregate a dotted verb names, when it is declared
+        def verb_aggregate(runtime, verb)
+          domain, rest = verb.split("::", 2)
+          aggregate_name = rest.to_s.split(".", 2).first
+          runtime.registry.bluebook(domain)&.aggregate(aggregate_name)
+        end
+
+        # Splits a mixed dispatch (receiver identity plus declared facts, e.g.
+        # `to: { file: 2, rank: 2 }`) into the dispatcher's strict `to:`/`with:` envelope.
+        #
+        # @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 facts, mixing identity and declared arguments
+        # @return [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the dispatch
+        #   result
+        # @raise [Runtime::UnknownVerb] if `verb` names an undeclared construct
+        # @raise [StandardError] any `Runtime::DOMAIN_REFUSALS` class, when the domain refuses
+        def dispatch_command(runtime, verb, args)
+          return runtime.dispatch_flat(verb, args) if port_operation?(runtime, verb)
+
+          invocation = reaction_invocation(runtime, verb, args)
+          return runtime.dispatch_flat(verb, args) unless invocation
+
+          if invocation.key?(:to)
+            runtime.dispatch(verb, to: invocation[:to], with: invocation[:with])
+          else
+            runtime.dispatch(verb, with: invocation[:with])
+          end
+        end
+
+        # @return [Hash, nil] the strict envelope for `verb`, or nil when `verb` is not a declared
+        #   command
+        def reaction_invocation(runtime, verb, args)
+          Runtime::ReactionInvocation.build(registry: runtime.registry, verb: verb,
+                                            projected: args, explicit: true)
+        rescue Runtime::UnknownVerb
+          nil
+        end
+
+        # The same "Head.Rest" split `Dispatcher#dispatch` already uses — just a
+        # domain/aggregate and port-name lookup, no command resolution needed.
+        #
+        # @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
+
+          aggregate = runtime.registry.bluebook(domain)&.aggregate(aggregate_name)
+          return false unless aggregate
+
+          head, rest = command_path.split(".", 2)
+          rest && !!aggregate.port(head)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/behaviors/expectations/qualify.rb

@@ -0,0 +1,81 @@
+module Hecks
+  module Behaviors
+    module Expectations
+      # Resolves a bare command or query name to the one dotted FQN that declares it. Extended onto
+      # `Expectations`.
+      module Qualify
+        # Searches every aggregate of every bluebook the suite booted for the one
+        # declaring `command`; `on:` narrows the search to one aggregate by name.
+        #
+        # @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?(".")
+
+          candidates = qualify_candidates(command, on_aggregate, bluebooks, kind)
+          disambiguate_qualified_name(candidates, command, kind, bluebooks)
+        end
+
+        # Finds 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
+          aggregate_pairs(bluebooks, on_aggregate)
+            .select { |_, agg| agg.public_send(members).any? { |m| m.hecks_name == command.to_s } }
+        end
+
+        # @return [Array<Array(Bluebook::Chapter, Bluebook::Aggregate)>] the named aggregate of
+        #   each chapter that has it, or every aggregate of every chapter when none is named
+        def aggregate_pairs(bluebooks, on_aggregate)
+          return bluebooks.flat_map { |bb| bb.aggregates.map { |agg| [bb, agg] } } unless on_aggregate
+
+          bluebooks.filter_map { |bb| (agg = bb.aggregate(on_aggregate)) && [bb, agg] }
+        end
+
+        # Resolves a search's candidates to exactly one dotted FQN; zero or more
+        # than one both refuse, each with a different message.
+        #
+        # @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)
+          raise ArgumentError, undeclared_message(command, kind, bluebooks) if candidates.empty?
+          raise ArgumentError, ambiguous_message(command, candidates) if candidates.size > 1
+
+          bluebook, aggregate = candidates.first
+          "#{bluebook.name}::#{aggregate.name}.#{command}"
+        end
+
+        def undeclared_message(command, kind, bluebooks)
+          "no aggregate among #{bluebooks.map(&:name).inspect} declares a #{kind} " \
+            "named #{command.inspect} — say `on:` if it's ambiguous, or check the spelling"
+        end
+
+        def ambiguous_message(command, candidates)
+          owners = candidates.map { |bb, agg| "#{bb.name}::#{agg.name}" }
+          "#{command.inspect} is declared on more than one aggregate (#{owners.join(", ")}) " \
+            "— say `on:` to disambiguate, or use the dotted FQN"
+        end
+      end
+    end
+  end
+end