hegeltest 0.1.0

data/lib/hegel/state_machine.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "syntax/methods"
+
+module Hegel
+  # Base class for a stateful (model-based) test's machine: a subclass
+  # declares its actions with the class-level #rule and #invariant macros,
+  # then Hegel::Stateful.run drives one instance of it inside an ordinary
+  # Hegel.test block. See docs/adr/0010 for the declared shape (a class with
+  # macros, not a method-naming convention or an instance-built list) and
+  # the reasons behind it.
+  #
+  # Only declaration lives here. Hegel::Stateful.run owns the loop that
+  # calls the declared blocks, the same split hegel-rust draws between its
+  # StateMachine trait (rules()/invariants()) and its own free function
+  # `run`.
+  class StateMachine
+    # So a rule or invariant block can call a generator method (integers,
+    # arrays, and so on) bare, the same way a Hegel.test block already can
+    # via the caller's own include -- see docs/adr/0010's own reasoning for
+    # why a machine needs this itself rather than inheriting its test
+    # class's.
+    include Syntax::Methods
+
+    class << self
+      # Declares a rule named +name+: an action the engine may pick to run
+      # at any step. +block+ runs via #instance_exec against the machine
+      # instance being tested, and is handed the running Hegel::TestCase as
+      # its one argument -- ignored if the block declares no parameter, the
+      # ordinary Ruby block rule.
+      def rule(name, &block)
+        declare(:@rules, "rule", name, block)
+      end
+
+      # Declares an invariant named +name+, checked once before the first
+      # rule runs and again after every rule that completes without its own
+      # assumption failing. Same block/argument contract as #rule.
+      def invariant(name, &block)
+        declare(:@invariants, "invariant", name, block)
+      end
+
+      # name => block, in declaration order, this class's own declarations
+      # merged over its ancestors'. Hegel::Stateful.run reads this directly
+      # to build the ordered rule-name list libhegel indexes by position.
+      def rule_definitions
+        merged_definitions(:@rules, :rule_definitions)
+      end
+
+      # The invariant analogue of #rule_definitions.
+      def invariant_definitions
+        merged_definitions(:@invariants, :invariant_definitions)
+      end
+
+      private
+
+      # Adds +name+ (stringified, so a Symbol and the same-named String
+      # collide) to the table at +ivar+, raising Hegel::Error when *this*
+      # class already declares one by that name -- the disappearing-rule
+      # failure docs/adr/0010 exists to turn into a raise instead. A name
+      # only a superclass declared is not a collision here: #declare never
+      # reads an ancestor's table, so a subclass re-declaring an inherited
+      # name is the ordinary "redefine a method" case the ADR calls out,
+      # not this one.
+      def declare(ivar, kind, name, block)
+        table = instance_variable_get(ivar) || instance_variable_set(ivar, {})
+        name = name.to_s
+        raise Hegel::Error, "hegel: #{kind} #{name.inspect} is already declared on #{self}" if table.key?(name)
+
+        table[name] = block
+      end
+
+      # Shared by #rule_definitions/#invariant_definitions: this class's own
+      # table layered over its superclass's already-merged one via
+      # Hash#merge, so a name declared on both keeps the position it first
+      # held (Hash#merge's own behaviour for a key present in both operands)
+      # while every new name from this class is appended -- together, the
+      # declaration order the whole ancestor chain built. Recursion stops at
+      # the first class that does not respond to +reader+ (Object, past
+      # Hegel::StateMachine's own top), rather than comparing against
+      # StateMachine directly, so nothing here hard-codes this one class as
+      # the root.
+      def merged_definitions(ivar, reader)
+        inherited = superclass.respond_to?(reader) ? superclass.public_send(reader) : {}
+        inherited.merge(instance_variable_get(ivar) || {})
+      end
+    end
+  end
+end

data/lib/hegel/stateful/pool.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "../generator"
+
+module Hegel
+  module Stateful
+    # A pool of previously generated values, for a later stateful rule to
+    # draw one back out. Build one from the running test case, inside the
+    # machine's own constructor:
+    #
+    #   Hegel::Stateful::Pool.new(tc)
+    #
+    # #add records a value under a fresh variable id (hegel_pool_add); #size
+    # and #empty? read the Ruby-side count directly. Drawing goes through the
+    # two generators below, not through this class's own storage, so a
+    # chosen id is drawn (and shrunk, and recorded in a failure report) the
+    # same way any other value is: #values_reusable leaves the drawn value in
+    # the pool, #values_consumed removes it. hegel-rust's own Pool<T>
+    # (src/stateful.rs) keeps the same three-way split between the engine's
+    # variable-id choice, this class's own id-to-value map, and the two
+    # generators.
+    #
+    # A caller never frees a pool. docs/adr/0011 has the reason: #initialize
+    # opens the native handle through Hegel::TestCase#new_pool, which records
+    # it on +tc+ itself, and Hegel::Runner frees every pool a test case
+    # recorded once that test case is done -- the same "the test case owns
+    # what it opened" split this library already uses for a state-machine
+    # handle.
+    class Pool
+      def initialize(tc)
+        @tc = tc
+        @pool = tc.new_pool
+        @values = {}
+      end
+
+      # Number of values currently in the pool.
+      def size
+        @values.size
+      end
+
+      # True when no values are in the pool.
+      def empty?
+        @values.empty?
+      end
+
+      # Records +value+ under a fresh variable id from hegel_pool_add.
+      # Returns self, Set#add's own contract -- hegel-rust's own Pool::add
+      # returns nothing instead, since Rust has no builder-chaining idiom for
+      # this method to match.
+      def add(value)
+        variable_id = @tc.pool_add(@pool)
+        @values[variable_id] = value
+        self
+      end
+
+      # A Hegel::Generator over this pool's values: drawing it leaves the
+      # chosen value in place, so the same value can be drawn again.
+      def values_reusable
+        ValuesReusable.new(@pool, @values)
+      end
+
+      # A Hegel::Generator over this pool's values: drawing it removes the
+      # chosen value, so it is never drawn again.
+      def values_consumed
+        ValuesConsumed.new(@pool, @values)
+      end
+
+      # Hegel::Generator returned by Pool#values_reusable. Left un-namespaced
+      # under Hegel::Generators, the same way Hegel::Generator::Mapped and
+      # ::Filtered are: reached only through Pool#values_reusable, not part
+      # of this library's own public generator vocabulary.
+      class ValuesReusable < Generator
+        def initialize(pool, values)
+          super()
+          @pool = pool
+          @values = values
+        end
+
+        # Does not check @values.empty? before drawing: hegel_pool_generate
+        # already answers HEGEL_E_ASSUME for an empty pool, which
+        # Hegel::LibHegel.check! already translates to Hegel::AssumeFailed --
+        # the same translation every other assumption failure gets.
+        # hegel-rust's own ValuesReusable calls tc.assume ahead of its own
+        # pool_generate call (src/stateful.rs). Here the engine's answer is
+        # the single path, so the empty case has one place to change.
+        def do_draw(tc)
+          variable_id = tc.pool_generate(@pool, false)
+          @values.fetch(variable_id)
+        end
+      end
+
+      # Hegel::Generator returned by Pool#values_consumed. Same reasoning as
+      # ValuesReusable above for staying un-namespaced and for not
+      # pre-checking emptiness.
+      class ValuesConsumed < Generator
+        def initialize(pool, values)
+          super()
+          @pool = pool
+          @values = values
+        end
+
+        def do_draw(tc)
+          variable_id = tc.pool_generate(@pool, true)
+          value = @values.fetch(variable_id)
+          @values.delete(variable_id)
+          value
+        end
+      end
+    end
+  end
+end

data/lib/hegel/stateful.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "lib_hegel"
+require_relative "stateful/pool"
+
+module Hegel
+  # Runs one stateful (model-based) test: drives libhegel's own state-machine
+  # loop (hegel_new_state_machine and the three calls that go with it) against
+  # a Hegel::StateMachine instance's declared rules and invariants. Call it
+  # from inside an ordinary Hegel.test block, the same way any other draw
+  # happens:
+  #
+  #   Hegel.test { |tc| Hegel::Stateful.run(StackMachine.new, tc) }
+  #
+  # A module function, not a Hegel::StateMachine instance method, so that
+  # class stays limited to declaration -- the same split hegel-rust's own
+  # src/stateful.rs draws between the StateMachine trait and its free
+  # function `run`, which this module's own #run is ported from; see that
+  # file's comments for the reasoning behind the ordering below.
+  module Stateful
+    module_function
+
+    # +machine+ is a Hegel::StateMachine instance; +tc+ the running
+    # Hegel::TestCase.
+    #
+    # Raises Hegel::Error before making any libhegel call when +machine+
+    # declares no rules: hegel.h documents hegel_new_state_machine's
+    # rule_names as required to be non-empty, and there is nothing useful to
+    # run without one.
+    def run(machine, tc)
+      rules = machine.class.rule_definitions
+      raise Hegel::Error, "hegel: #{machine.class} has no rules; declare at least one with `rule`" if rules.empty?
+
+      invariants = machine.class.invariant_definitions
+      rule_names = rules.keys
+      state_machine = tc.new_state_machine(rule_names, invariants.keys)
+      begin
+        tc.note { "Initial invariant check." }
+        run_invariants(machine, invariants, tc)
+        drive(machine, rules, rule_names, invariants, state_machine, tc)
+      ensure
+        tc.state_machine_free(state_machine)
+      end
+    end
+
+    # Repeatedly asks +state_machine+ for the next rule to run and applies
+    # it, until libhegel reports the step budget for this test case spent.
+    #
+    # Measured against libhegel 0.32.5, unseeded, on the capacity-2 stack
+    # shrink-quality test below (test/hegel/test_stateful.rb,
+    # test_stateful_run_shrinks_to_the_minimal_step_count_that_breaks_the_
+    # invariant): closing the HEGEL_LABEL_STATEFUL_RULE span with
+    # stop_span(discard: false) on the DONE branch, right before breaking
+    # out of this loop, and leaving it open instead (matching hegel-rust's
+    # own `run`, which never closes that last span) both shrink the same
+    # failure to the same 3-step counterexample every time, 20 runs each.
+    # This keeps hegel-rust's own choice -- an unclosed span at DONE --
+    # since nothing measured favours the extra stop_span call.
+    def drive(machine, rules, rule_names, invariants, state_machine, tc)
+      steps_attempted = 0
+      loop do
+        tc.start_span(LibHegel::HEGEL_LABEL_STATEFUL_RULE)
+        rule_index = tc.state_machine_next_rule(state_machine)
+        break if rule_index == LibHegel::HEGEL_STATE_MACHINE_DONE
+
+        name = rule_names[rule_index]
+        steps_attempted += 1
+        tc.note { "Step #{steps_attempted}: #{name}" }
+        apply_rule(machine, rules.fetch(name), invariants, state_machine, tc)
+      end
+    end
+
+    # standard:disable Lint/RescueException -- deliberate, the same reason
+    # Hegel::Runner.classify's own `rescue Exception` is: Hegel::AssumeFailed
+    # and Hegel::StopTest both descend from Exception, not StandardError, so
+    # only `rescue Exception` sees every path a rule can take. Every branch
+    # other than AssumeFailed re-raises what it caught unchanged -- this
+    # never reclassifies an exception or swallows one, it only guarantees
+    # the span closes first, so a half-applied rule is never left mid-span
+    # when the exception unwinds past this method.
+    #
+    # Hegel::FATAL_EXCEPTIONS goes first and closes no span. They say the
+    # process is ending, so the span has no reader left to matter to, and
+    # answering a NoMemoryError with another native call is the wrong move.
+    # A rule is the one place in this library where a fatal exception is
+    # raised inside an open span, so this is where that ordering has to be
+    # written.
+    #
+    # tc.assume(false) inside a rule is not the same event as one raised
+    # directly inside a Hegel.test block: it rejects only this rule (told to
+    # libhegel via #state_machine_rule_rejected, so the rejected attempt
+    # does not count toward the step budget) and the loop keeps going, where
+    # Hegel::Runner.classify's own AssumeFailed handling discards the whole
+    # test case. Hegel::Runner.classify never sees this one: it is caught
+    # and handled right here.
+    def apply_rule(machine, block, invariants, state_machine, tc)
+      machine.instance_exec(tc, &block)
+    rescue *Hegel::FATAL_EXCEPTIONS
+      raise
+    rescue Hegel::AssumeFailed
+      tc.state_machine_rule_rejected(state_machine)
+      tc.stop_span(discard: true)
+      tc.note { "Rule stopped early due to violated assumption." }
+    rescue Exception
+      tc.stop_span(discard: false)
+      raise
+    else
+      tc.stop_span(discard: false)
+      run_invariants(machine, invariants, tc)
+    end
+    # standard:enable Lint/RescueException
+
+    # Runs every invariant, in declaration order, via #instance_exec -- same
+    # argument contract as a rule block (Hegel::StateMachine.invariant).
+    def run_invariants(machine, invariants, tc)
+      invariants.each_value { |block| machine.instance_exec(tc, &block) }
+    end
+  end
+end

data/lib/hegel/syntax/methods.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative "../generators"
+
+module Hegel
+  module Syntax
+    # The generator-constructing methods a caller can include to call bare,
+    # matching FactoryBot::Syntax::Methods's shape (see docs/adr/0004):
+    #
+    #   RSpec.configure { |config| config.include Hegel::Syntax::Methods }
+    #
+    # This is the one place any of these methods is defined.
+    # Hegel::Generators.<name> reaches the same methods without an
+    # include, via Hegel::Generators extending this module below.
+    module Methods
+      # A boolean, true with probability +p+.
+      def booleans(p: 0.5)
+        Generators::BooleanGenerator.new(p: p)
+      end
+
+      # An integer in [min_value, max_value], defaulting to the full
+      # 64-bit range when either bound is omitted.
+      def integers(min_value: nil, max_value: nil)
+        Generators::IntegerGenerator.new(min_value: min_value, max_value: max_value)
+      end
+
+      # A double in [min_value, max_value]. allow_nan and allow_infinity
+      # both default to false.
+      def floats(min_value: nil, max_value: nil, allow_nan: false, allow_infinity: false, exclude_min: false,
+        exclude_max: false)
+        Generators::FloatGenerator.new(
+          min_value: min_value, max_value: max_value, allow_nan: allow_nan, allow_infinity: allow_infinity,
+          exclude_min: exclude_min, exclude_max: exclude_max
+        )
+      end
+
+      # A Unicode string of [min_size, max_size] characters.
+      def text(min_size: 0, max_size: nil, codec: nil, min_codepoint: nil, max_codepoint: nil)
+        Generators::TextGenerator.new(
+          min_size: min_size, max_size: max_size, codec: codec,
+          min_codepoint: min_codepoint, max_codepoint: max_codepoint
+        )
+      end
+
+      # An Array of values from +elements+, with [min_size, max_size]
+      # entries.
+      def arrays(elements, min_size: 0, max_size: nil)
+        Generators::ArrayGenerator.new(elements, min_size: min_size, max_size: max_size)
+      end
+
+      # Always +value+, drawing nothing.
+      def just(value)
+        Generators::JustGenerator.new(value)
+      end
+
+      # One element of +collection+, picked at random.
+      def sampled_from(collection)
+        Generators::SampledFromGenerator.new(collection)
+      end
+
+      # A value drawn from one of +generators+, picked at random.
+      def one_of(*generators)
+        Generators::OneOfGenerator.new(generators)
+      end
+
+      # A value drawn from +generator+ half the time, nil the other half.
+      def optional(generator)
+        Generators::OptionalGenerator.new(generator)
+      end
+
+      # An Array holding one value drawn from each of +generators+, in
+      # order (Ruby has no tuple type; see docs/adr/0004).
+      def tuples(*generators)
+        Generators::TupleGenerator.new(generators)
+      end
+
+      # A Set of values from +elements+, with [min_size, max_size] entries.
+      def sets(elements, min_size: 0, max_size: nil)
+        Generators::SetGenerator.new(elements, min_size: min_size, max_size: max_size)
+      end
+
+      # A Hash whose keys are drawn from +keys+ and values from +values+,
+      # with [min_size, max_size] entries.
+      def hashes(keys, values, min_size: 0, max_size: nil)
+        Generators::HashGenerator.new(keys, values, min_size: min_size, max_size: max_size)
+      end
+
+      # A String of exactly one character, sharing #text's own alphabet
+      # options.
+      def characters(codec: nil, min_codepoint: nil, max_codepoint: nil)
+        Generators::CharactersGenerator.new(codec: codec, min_codepoint: min_codepoint, max_codepoint: max_codepoint)
+      end
+
+      # A byte String of [min_size, max_size] bytes.
+      def binary(min_size: 0, max_size: nil)
+        Generators::BinaryGenerator.new(min_size: min_size, max_size: max_size)
+      end
+
+      # A String matching +pattern+ (Python `re` syntax, not Ruby's
+      # Regexp syntax; see Generators::FromRegexGenerator). fullmatch
+      # requires the whole string to match, not just contain a match.
+      def from_regex(pattern, fullmatch: false)
+        Generators::FromRegexGenerator.new(pattern, fullmatch: fullmatch)
+      end
+
+      # An RFC 5321/5322 email address String.
+      def emails
+        Generators::EmailsGenerator.new
+      end
+
+      # An RFC 3986 http/https URL String.
+      def urls
+        Generators::UrlsGenerator.new
+      end
+
+      # A fully-qualified domain name String of at most +max_length+
+      # characters.
+      def domains(max_length: 255)
+        Generators::DomainsGenerator.new(max_length: max_length)
+      end
+
+      # An IPAddr, v4 or v6 depending on +v4+/+v6+ (see
+      # Generators::IpAddressesGenerator).
+      def ip_addresses(v4: true, v6: true)
+        Generators::IpAddressesGenerator.new(v4: v4, v6: v6)
+      end
+
+      # A UUID String in the standard 8-4-4-4-12 hex form. version: nil (the
+      # default) draws uniform random bits except the nil UUID; an explicit
+      # version forces the RFC 4122 version and variant nibbles (see
+      # Generators::UuidsGenerator).
+      def uuids(version: nil)
+        Generators::UuidsGenerator.new(version: version)
+      end
+
+      # A proleptic Gregorian calendar Date in [min_value, max_value],
+      # defaulting to year 1 through year 9999.
+      def dates(min_value: nil, max_value: nil)
+        Generators::DatesGenerator.new(min_value: min_value, max_value: max_value)
+      end
+
+      # A time of day String, "HH:MM:SS.ffffff", in [min_value, max_value]
+      # (also "HH:MM:SS.ffffff" Strings), defaulting to the full day.
+      def times(min_value: nil, max_value: nil)
+        Generators::TimesGenerator.new(min_value: min_value, max_value: max_value)
+      end
+
+      # A naive (no timezone) Time in [min_value, max_value], defaulting to
+      # year 1 through year 9999 (see Generators::DatetimesGenerator).
+      def datetimes(min_value: nil, max_value: nil)
+        Generators::DatetimesGenerator.new(min_value: min_value, max_value: max_value)
+      end
+
+      # A value built from imperative code: +block+ receives a draw
+      # surface and may call #draw on it any number of times to assemble
+      # one value (see Generators::CompositeGenerator).
+      def composite(&block)
+        Generators::CompositeGenerator.new(&block)
+      end
+
+      # A forward reference to a generator whose definition is supplied
+      # later via #set, enabling self-recursive and mutually recursive
+      # generators (see Generators::DeferredGenerator).
+      def deferred
+        Generators::DeferredGenerator.new
+      end
+    end
+  end
+
+  module Generators
+    extend Syntax::Methods
+  end
+end