hegeltest 0.3.4 → 0.4.0

data/docs/architecture.md

@@ -18,7 +18,7 @@ recorded, and prints a blob that `Hegel.test(reproduce_failure:)` replays.
 The report comes from the cases the engine stamps for capture during the
 run; see
 [ADR 0019](adr/0019-report-failures-from-the-cases-the-engine-stamps.md).
-The generator layer covers twenty-five generators composing through `map`
+The generator layer covers thirty-four generators composing through `map`
 and `filter`, reachable bare through `Hegel::Syntax::Methods`. A test case
 can discard itself with `tc.assume` or `tc.reject`. A run can be shaped by
 `phases:`, `suppress_health_check:`, `report_multiple_failures:`, and the
@@ -121,6 +121,12 @@ test-case handle, in nested `ensure`s so a failure releasing one cannot skip
 the other. See
 [ADR 0011](adr/0011-let-the-test-case-own-every-pool-drawn-from-it.md).
 
+A compiled grammar outlives the test case that compiled it, since compiling
+costs far more than drawing. `Hegel::Runner.run` keeps the run's grammars
+in a `Hegel::GrammarCache` and frees them after the run and before the
+context. See
+[ADR 0033](adr/0033-cache-compiled-grammars-for-the-length-of-a-run.md).
+
 ## A rule's own control flow
 
 Inside a stateful rule, `tc.assume(false)` means something narrower than it
@@ -135,6 +141,15 @@ exception can be raised inside an open span, which is why
 than beside the run loop: two `rescue Exception` sites need it now, and both
 have to let those four straight through before anything else.
 
+## An abandoned recursive attempt
+
+`recursive` unwinds through open spans on purpose. When an attempt outgrows its leaf budget, `Hegel::TestCase` raises
+`Hegel::LeafBudgetExceeded` and holds it until `hegel_recursion_retry`.
+Meanwhile `stop_span` makes no native call, so the retry can discard the
+spans the attempt opened, and every other call that takes the test-case
+handle raises the held exception again instead of reaching the engine. See
+[ADR 0032](adr/0032-suppress-span-closes-while-an-abandoned-recursion-attempt-unwinds.md).
+
 ## Generator validation happens at draw time
 
 hegel-rust's own contributor documentation states the rule for its

data/lib/hegel/errors.rb

@@ -31,6 +31,30 @@ module Hegel
   # Descends from Exception for the same reason as StopTest above.
   class AssumeFailed < Exception; end
 
+  # Raised for HEGEL_E_RETRY from hegel_recursion_leaf: the attempt at a
+  # recursive value outgrew its leaf budget and must unwind to the
+  # Generators::RecursiveGenerator that owns +recursion+, which retries it.
+  # Internal to this library. See docs/adr/0032.
+  class LeafBudgetExceeded < Exception # :nodoc:
+    attr_reader :recursion
+
+    def initialize(recursion)
+      super("hegel: a recursive draw outgrew its leaf budget; the attempt is retried")
+      @recursion = recursion
+    end
+  end
+
+  # Raised by Hegel::TestCase#repeat when the engine ends its loop: the
+  # repetition ran as long as the engine wanted it to and nothing failed,
+  # so Hegel::Runner.classify reports the case VALID. hegel-rust raises its
+  # own LoopDone at the same point, and its run lifecycle maps it to VALID
+  # the same way.
+  #
+  # Descends from Exception for the same reason as StopTest above: a
+  # `rescue => e` written after the loop must not turn the end of the loop
+  # into ordinary control flow. See docs/adr/0034.
+  class LoopDone < Exception; end
+
   # standard:enable Lint/InheritException
 
   # Say the process is ending, not that a property failed. Every

data/lib/hegel/generator.rb

@@ -18,6 +18,41 @@ module Hegel
       raise NotImplementedError, "#{self.class} must implement #do_draw"
     end
 
+    # The span label of one attempt at a filtered draw, shared by every
+    # generator that runs attempts.
+    FILTER_ATTEMPT_LABEL = LibHegel.label_from_name("hegel-ruby.Hegel::Generator.filter_attempt")
+
+    # Draws one value that +predicate+ accepts, the draw behind #filter, which
+    # calls this on its source generator. The default makes up to
+    # Filtered::MAX_ATTEMPTS attempts, each a #do_draw in a span of its own
+    # that closes as discarded when the predicate rejects the value, then
+    # discards the test case (Hegel::AssumeFailed).
+    #
+    # A generator whose draws have effects a rejected value must not keep
+    # overrides this and runs the attempts itself, as
+    # Hegel::Stateful::Pool::ValuesConsumed does. One that only forwards
+    # #do_draw to another generator forwards this too, so that a filter around
+    # it still reaches the other generator's attempts.
+    def do_draw_filtered(tc, predicate)
+      Filtered::MAX_ATTEMPTS.times do
+        # Each variable is set again before it is read, or stays nil, which
+        # acts like false (!nil == !false).
+        # The initializer also shows intent: discard the span when an
+        # exception skips the reassignment.
+        accepted = false # mutineer:disable-line statement_removal
+        value = nil # mutineer:disable-line statement_removal, boolean_literal
+        tc.start_span(FILTER_ATTEMPT_LABEL)
+        begin
+          value = do_draw(tc)
+          accepted = predicate.call(value)
+        ensure
+          tc.stop_span(discard: !accepted)
+        end
+        return value if accepted
+      end
+      raise Hegel::AssumeFailed
+    end
+
     # The span label naming this generator's draws to the engine, which
     # treats two spans with one label as draws of one generator when it
     # shrinks. A generator built from others overrides this and combines
@@ -30,7 +65,7 @@ module Hegel
     # The class name, prefixed with this binding's name as hegel.h asks, to
     # keep clear of the engine's own hegel.<kind> labels.
     def self.label
-      LibHegel.label_from_name("hegel-ruby.#{name}")
+      @label ||= LibHegel.label_from_name("hegel-ruby.#{name}")
     end
 
     # Combines this generator's class label with the labels of +parts+, the
@@ -92,13 +127,17 @@ module Hegel
       end
     end
 
-    # Generator#filter's result. Retries the source generator, each
-    # attempt in its own span, up to MAX_ATTEMPTS times before discarding
-    # the test case (Hegel::AssumeFailed) -- the same budget hegel-rust's
-    # Filtered spends before calling assume(false)
-    # (src/generators/generators.rs), ported here rather than reinvented so
-    # a predicate that (almost) never holds fails the same way in both
-    # bindings.
+    # Generator#filter's result. Hands its predicate to the source
+    # generator's #do_draw_filtered, which makes up to MAX_ATTEMPTS attempts
+    # before discarding the test case (Hegel::AssumeFailed) -- the same
+    # budget hegel-rust's Filtered spends before calling assume(false)
+    # (frontends/rust/src/generators/generators.rs), ported here rather than
+    # reinvented so a predicate that (almost) never holds fails the same way
+    # in both bindings.
+    #
+    # A filter over a filter combines the two predicates into one draw, so
+    # the pair spends MAX_ATTEMPTS attempts between them, not that many per
+    # level.
     #
     # A predicate that never holds does not loop forever: libhegel's own
     # health check aborts a run that discards too many test cases in a
@@ -116,23 +155,11 @@ module Hegel
       attr_reader :label
 
       def do_draw(tc)
-        MAX_ATTEMPTS.times do
-          # Each variable is set again before it is read, or stays nil, which
-          # acts like false (!nil == !false).
-          # The initializer also shows intent: discard the span when an
-          # exception skips the reassignment.
-          accepted = false # mutineer:disable-line statement_removal
-          value = nil # mutineer:disable-line statement_removal, boolean_literal
-          tc.start_span(label)
-          begin
-            value = @source.do_draw(tc)
-            accepted = @block.call(value)
-          ensure
-            tc.stop_span(discard: !accepted)
-          end
-          return value if accepted
-        end
-        raise Hegel::AssumeFailed
+        @source.do_draw_filtered(tc, @block)
+      end
+
+      def do_draw_filtered(tc, predicate)
+        @source.do_draw_filtered(tc, ->(value) { @block.call(value) && predicate.call(value) })
       end
     end
   end