hegeltest 0.1.1 → 0.2.0

data/lib/hegel/generators.rb

@@ -22,7 +22,6 @@ module Hegel
     # Hegel::Syntax::Methods#booleans. A boolean, true with probability +p+.
     class BooleanGenerator < Generator
       def initialize(p:)
-        super()
         @p = p
       end
 
@@ -45,7 +44,6 @@ module Hegel
       INT64_MAX = (2**63) - 1
 
       def initialize(min_value:, max_value:)
-        super()
         @min_value = min_value
         @max_value = max_value
       end
@@ -64,22 +62,28 @@ module Hegel
     end
 
     # Hegel::Syntax::Methods#floats. A double in [min_value, max_value],
-    # unbounded (the full finite range) by default. allow_nan and
-    # allow_infinity both default to false here, unlike hegel-rust's
-    # floats() (true when neither bound is set): this milestone exposes a
-    # plain, always-off-by-default surface and leaves
-    # smallest_nonzero_magnitude, and the allow_nan/allow_infinity/bounds
-    # interaction hegel-rust validates, unexposed. A caller who never asks
-    # for NaN never has to reason about it, and a keyword can be added to
-    # this list later without breaking anyone, where a default flipped from
-    # true to false would.
+    # unbounded by default.
+    #
+    # allow_nan and allow_infinity are three-valued: nil asks for the
+    # default the bounds imply, and true or false overrides it. Three
+    # implementations write that default as the same pair of expressions --
+    # hegel-rust's src/generators/numeric.rs, hegel-go's primitives.go, and
+    # hegel-typescript's src/generators/numeric.ts -- so an unbounded
+    # floats() draws NaN and both infinities, and a fully bounded one draws
+    # neither. docs/adr/0015 decides to follow that surface rather than the
+    # always-off one this generator carried through 0.1.1.
+    #
+    # The two checks below come with those defaults: hegel-rust and
+    # hegel-go each raise on the same two combinations, and the messages
+    # here carry the substring theirs do. smallest_nonzero_magnitude and
+    # allow_subnormal, which hegel-rust also exposes, stay unexposed; a
+    # keyword can be added later without breaking a caller.
     class FloatGenerator < Generator
       # hegel_generate_float's width; Ruby has one Float type, the 64-bit
       # IEEE 754 double, so this is never anything else.
       WIDTH = 64
 
       def initialize(min_value:, max_value:, allow_nan:, allow_infinity:, exclude_min:, exclude_max:)
-        super()
         @min_value = min_value
         @max_value = max_value
         @allow_nan = allow_nan
@@ -89,13 +93,25 @@ module Hegel
       end
 
       def do_draw(tc)
+        has_min = !@min_value.nil?
+        has_max = !@max_value.nil?
+        allow_nan = @allow_nan.nil? ? !has_min && !has_max : @allow_nan
+        allow_infinity = @allow_infinity.nil? ? !has_min || !has_max : @allow_infinity
+
+        if allow_nan && (has_min || has_max)
+          raise Hegel::Error, "floats: cannot have allow_nan=true with min_value or max_value"
+        end
+        if allow_infinity && has_min && has_max
+          raise Hegel::Error, "floats: cannot have allow_infinity=true with both min_value and max_value"
+        end
+
         min_value = @min_value || -Float::INFINITY
         max_value = @max_value || Float::INFINITY
         raise Hegel::Error, "floats: max_value < min_value" if max_value < min_value
 
         tc.generate_float(
           WIDTH, min_value, max_value,
-          allow_nan: @allow_nan, allow_infinity: @allow_infinity,
+          allow_nan: allow_nan, allow_infinity: allow_infinity,
           exclude_min: @exclude_min, exclude_max: @exclude_max,
           smallest_nonzero_magnitude: LibHegel::HEGEL_FLOAT64_SMALLEST_NONZERO_MAGNITUDE_UNRESTRICTED
         )
@@ -106,7 +122,6 @@ module Hegel
     # characters, unbounded above by default.
     class TextGenerator < Generator
       def initialize(min_size:, max_size:, codec:, min_codepoint:, max_codepoint:)
-        super()
         @min_size = min_size
         @max_size = max_size
         @codec = codec
@@ -140,25 +155,27 @@ module Hegel
     # with [min_size, max_size] entries, unbounded above by default.
     class ArrayGenerator < Generator
       def initialize(elements, min_size:, max_size:)
-        super()
         @elements = elements
         @min_size = min_size
         @max_size = max_size
+        @label = combined_label(@elements)
       end
 
+      attr_reader :label
+
       def do_draw(tc)
         raise Hegel::Error, "arrays: min_size must not be negative" if @min_size.negative?
 
         max_size = @max_size || LibHegel::HEGEL_COLLECTION_MAX_SIZE_UNBOUNDED
         raise Hegel::Error, "arrays: max_size < min_size" if max_size < @min_size
 
-        # HEGEL_LABEL_LIST around the whole array, HEGEL_LABEL_LIST_ELEMENT
-        # around each element (#draw_element below): the reference binding
-        # (hegel-typescript's drawList) wraps both, and the shrinker needs
-        # both to shrink a compound draw correctly -- a missing or
-        # misplaced span here shows up as a larger-than-minimal
-        # counterexample, not a test failure (see docs/adr/0006).
-        tc.start_span(LibHegel::HEGEL_LABEL_LIST)
+        # One span around the whole array, and one around each element
+        # (#draw_element below) labelled with the element generator's own
+        # label: the shrinker needs both to shrink a compound draw
+        # correctly. A missing or misplaced span here shows up as a
+        # larger-than-minimal counterexample, not a test failure (see
+        # docs/adr/0006).
+        tc.start_span(label)
         begin
           draw_elements(tc, max_size)
         ensure
@@ -180,7 +197,7 @@ module Hegel
       end
 
       def draw_element(tc)
-        tc.start_span(LibHegel::HEGEL_LABEL_LIST_ELEMENT)
+        tc.start_span(@elements.label)
         @elements.do_draw(tc)
       ensure
         tc.stop_span(discard: false)
@@ -193,7 +210,6 @@ module Hegel
     # nothing here to retry or isolate).
     class JustGenerator < Generator
       def initialize(value)
-        super()
         @value = value
       end
 
@@ -206,14 +222,13 @@ module Hegel
     # picked by drawing an index in [0, collection.size - 1].
     class SampledFromGenerator < Generator
       def initialize(collection)
-        super()
         @collection = collection
       end
 
       def do_draw(tc)
         raise Hegel::Error, "sampled_from: collection must not be empty" if @collection.empty?
 
-        tc.start_span(LibHegel::HEGEL_LABEL_SAMPLED_FROM)
+        tc.start_span(label)
         begin
           index = tc.generate_integer(0, @collection.size - 1)
           @collection.to_a[index]
@@ -227,14 +242,16 @@ module Hegel
     # by drawing an index in [0, generators.size - 1].
     class OneOfGenerator < Generator
       def initialize(generators)
-        super()
         @generators = generators
+        @label = combined_label(*@generators)
       end
 
+      attr_reader :label
+
       def do_draw(tc)
         raise Hegel::Error, "one_of: at least one generator is required" if @generators.empty?
 
-        tc.start_span(LibHegel::HEGEL_LABEL_ONE_OF)
+        tc.start_span(label)
         begin
           index = tc.generate_integer(0, @generators.size - 1)
           @generators[index].do_draw(tc)
@@ -249,12 +266,14 @@ module Hegel
     # milestone leaves generate_boolean at its own default probability.
     class OptionalGenerator < Generator
       def initialize(generator)
-        super()
         @generator = generator
+        @label = combined_label(@generator)
       end
 
+      attr_reader :label
+
       def do_draw(tc)
-        tc.start_span(LibHegel::HEGEL_LABEL_OPTIONAL)
+        tc.start_span(label)
         begin
           tc.generate_boolean ? @generator.do_draw(tc) : nil
         ensure
@@ -264,18 +283,20 @@ module Hegel
     end
 
     # Hegel::Syntax::Methods#tuples. Draws each of +generators+ in order
-    # into an Array (Ruby has no tuple type; see docs/adr/0004). The label
-    # table assigns tuples a single span around the whole draw, unlike
-    # arrays/sets/hashes: each position is a distinct generator already,
-    # not repeated draws of one, so there is no per-element span to open.
+    # into an Array (Ruby has no tuple type; see docs/adr/0004). One span
+    # goes around the whole draw, unlike arrays/sets/hashes: each position
+    # is a distinct generator already, not repeated draws of one, so there
+    # is no per-element span to open.
     class TupleGenerator < Generator
       def initialize(generators)
-        super()
         @generators = generators
+        @label = combined_label(*@generators)
       end
 
+      attr_reader :label
+
       def do_draw(tc)
-        tc.start_span(LibHegel::HEGEL_LABEL_TUPLE)
+        tc.start_span(label)
         begin
           @generators.map { |generator| generator.do_draw(tc) }
         ensure
@@ -288,19 +309,21 @@ module Hegel
     # [min_size, max_size] entries, unbounded above by default.
     class SetGenerator < Generator
       def initialize(elements, min_size:, max_size:)
-        super()
         @elements = elements
         @min_size = min_size
         @max_size = max_size
+        @label = combined_label(@elements)
       end
 
+      attr_reader :label
+
       def do_draw(tc)
         raise Hegel::Error, "sets: min_size must not be negative" if @min_size.negative?
 
         max_size = @max_size || LibHegel::HEGEL_COLLECTION_MAX_SIZE_UNBOUNDED
         raise Hegel::Error, "sets: max_size < min_size" if max_size < @min_size
 
-        tc.start_span(LibHegel::HEGEL_LABEL_SET)
+        tc.start_span(label)
         begin
           draw_elements(tc, max_size)
         ensure
@@ -334,7 +357,7 @@ module Hegel
       end
 
       def draw_element(tc)
-        tc.start_span(LibHegel::HEGEL_LABEL_SET_ELEMENT)
+        tc.start_span(@elements.label)
         @elements.do_draw(tc)
       ensure
         tc.stop_span(discard: false)
@@ -348,21 +371,26 @@ module Hegel
     # nothing, so it is rejected the same way SetGenerator rejects a
     # duplicate element.
     class HashGenerator < Generator
+      ENTRY_LABEL = LibHegel.label_from_name("hegel-ruby.Hegel::Generators::HashGenerator.entry")
+
       def initialize(keys, values, min_size:, max_size:)
-        super()
         @keys = keys
         @values = values
         @min_size = min_size
         @max_size = max_size
+        @label = combined_label(@keys, @values)
+        @entry_label = LibHegel.label_combine([ENTRY_LABEL, *[@keys, @values].map { |part| Generator.label_of(part) }])
       end
 
+      attr_reader :label
+
       def do_draw(tc)
         raise Hegel::Error, "hashes: min_size must not be negative" if @min_size.negative?
 
         max_size = @max_size || LibHegel::HEGEL_COLLECTION_MAX_SIZE_UNBOUNDED
         raise Hegel::Error, "hashes: max_size < min_size" if max_size < @min_size
 
-        tc.start_span(LibHegel::HEGEL_LABEL_MAP)
+        tc.start_span(label)
         begin
           draw_entries(tc, max_size)
         ensure
@@ -390,12 +418,11 @@ module Hegel
         end
       end
 
-      # Draws the key and its value as one unit inside a single
-      # HEGEL_LABEL_MAP_ENTRY span (the label table gives hashes one span
-      # per entry, not one per key and a second per value), so the
-      # shrinker can retry the whole pair together.
+      # Draws the key and its value as one unit inside a single span, so the
+      # shrinker can retry the whole pair together. The entry label combines
+      # the key and value labels, as the hash's own label does.
       def draw_entry(tc)
-        tc.start_span(LibHegel::HEGEL_LABEL_MAP_ENTRY)
+        tc.start_span(@entry_label)
         [@keys.do_draw(tc), @values.do_draw(tc)]
       ensure
         tc.stop_span(discard: false)
@@ -411,7 +438,6 @@ module Hegel
     # delegated #do_draw is the whole draw, not a composition of several.
     class CharactersGenerator < Generator
       def initialize(codec:, min_codepoint:, max_codepoint:)
-        super()
         @text = TextGenerator.new(
           min_size: 1, max_size: 1, codec: codec,
           min_codepoint: min_codepoint, max_codepoint: max_codepoint
@@ -427,7 +453,6 @@ module Hegel
     # bytes, unbounded above by default.
     class BinaryGenerator < Generator
       def initialize(min_size:, max_size:)
-        super()
         @min_size = min_size
         @max_size = max_size
       end
@@ -473,7 +498,6 @@ module Hegel
     # passing here.
     class FromRegexGenerator < Generator
       def initialize(pattern, fullmatch:)
-        super()
         @pattern = pattern
         @fullmatch = fullmatch
       end
@@ -514,7 +538,6 @@ module Hegel
     # only repeat the engine's own validation with a worse message.
     class DomainsGenerator < Generator
       def initialize(max_length:)
-        super()
         @max_length = max_length
       end
 
@@ -529,16 +552,14 @@ module Hegel
     # so it raises here rather than reaching hegel_generate_ipv4 or
     # hegel_generate_ipv6 at all.
     #
-    # Spanned with HEGEL_LABEL_IP_ADDRESS around the whole draw, the same
-    # way OptionalGenerator spans its own boolean-then-delegate draw
-    # (see the HEGEL_LABEL_* table): when both families are enabled this
+    # Spanned around the whole draw, the same way OptionalGenerator spans
+    # its own boolean-then-delegate draw: when both families are enabled this
     # generator makes two native calls (the family choice, then the
     # address) to produce one value, and the span is what lets the
     # shrinker retry that pair together instead of the two calls
     # separately.
     class IpAddressesGenerator < Generator
       def initialize(v4:, v6:)
-        super()
         @v4 = v4
         @v6 = v6
       end
@@ -546,7 +567,7 @@ module Hegel
       def do_draw(tc)
         raise Hegel::Error, "ip_addresses: v4 and v6 must not both be false" if !@v4 && !@v6
 
-        tc.start_span(LibHegel::HEGEL_LABEL_IP_ADDRESS)
+        tc.start_span(label)
         begin
           draw_address(tc)
         ensure
@@ -576,19 +597,15 @@ module Hegel
     # draws uniform random bits except the nil UUID, per the header; an
     # explicit version forces the RFC 4122 version and variant nibbles.
     #
-    # Opens no span: HEGEL_LABEL_UUID is a per-draw label the engine itself
-    # emits inside hegel_generate_uuid, not something this binding opens --
-    # the header's own comment on HEGEL_LABEL_INTEGER says the same of
-    # hegel_generate_integer/_big ("Emitted internally, like every per-draw
-    # label"). BooleanGenerator, IntegerGenerator, and FloatGenerator each
-    # make exactly one native call to produce their own value the same way
-    # uuids() does here, and each opens no span of its own for the same
-    # reason. A span belongs only around a generator that composes more
-    # than one native call into one draw (see IpAddressesGenerator, whose
-    # family choice and address draw are two calls under one span).
+    # Opens no span: hegel_generate_uuid is one native call, and the engine
+    # labels the spans around its own draws itself. BooleanGenerator,
+    # IntegerGenerator, and FloatGenerator each make exactly one native call
+    # the same way, and open no span of their own for the same reason. A
+    # span belongs only around a generator that composes more than one
+    # native call into one draw (see IpAddressesGenerator, whose family
+    # choice and address draw are two calls under one span).
     class UuidsGenerator < Generator
       def initialize(version:)
-        super()
         @version = version
       end
 
@@ -606,19 +623,12 @@ module Hegel
     # own src/test_case.rs names this full_ranges::MIN_DATE/MAX_DATE, "what
     # Hypothesis's dates() spans".
     #
-    # Opens no span: hegel_generate_date makes exactly one native call to
-    # produce its own value, and the header's own comment on
-    # HEGEL_LABEL_REGEX ("callers normally never open this span themselves.
-    # Likewise for the other engine-side compound draws below") covers
-    # HEGEL_LABEL_DATE too, since it sits below REGEX in that same list --
-    # the same one-native-call, no-span-of-our-own reasoning UuidsGenerator's
-    # own comment already gives for HEGEL_LABEL_UUID.
+    # Opens no span, for the reason UuidsGenerator gives: one native call.
     class DatesGenerator < Generator
       MIN_DATE = Date.new(1, 1, 1)
       MAX_DATE = Date.new(9999, 12, 31)
 
       def initialize(min_value:, max_value:)
-        super()
         @min_value = min_value
         @max_value = max_value
       end
@@ -635,6 +645,22 @@ module Hegel
       end
     end
 
+    # Since libhegel 0.36 the engine draws a time of day in whole
+    # nanoseconds. times and datetimes keep microseconds, because hegel-rust,
+    # hegel-cpp, and hegel-typescript do not agree on a finer precision. A
+    # bound's microsecond widens to every nanosecond inside it, and the
+    # drawn value rounds down, so every microsecond in range stays
+    # reachable, both bounds included.
+    def self.first_nanosecond(parts)
+      hour, minute, second, microsecond = parts
+      [hour, minute, second, microsecond * 1000]
+    end
+
+    def self.last_nanosecond(parts)
+      hour, minute, second, microsecond = parts
+      [hour, minute, second, (microsecond * 1000) + 999]
+    end
+
     # Hegel::Syntax::Methods#times. A time of day String, "HH:MM:SS.ffffff",
     # in [min_value, max_value] (also "HH:MM:SS.ffffff" Strings), defaulting
     # to the conventional full day (00:00:00.000000 through 23:59:59.999999
@@ -651,9 +677,7 @@ module Hegel
     # representation, both for symmetry with the return value and because
     # it is the only representation available on the input side either.
     #
-    # Opens no span, for the same reason DatesGenerator does not (one
-    # native call, HEGEL_LABEL_TIME sits below HEGEL_LABEL_REGEX in the same
-    # header list).
+    # Opens no span, for the reason UuidsGenerator gives: one native call.
     class TimesGenerator < Generator
       MIDNIGHT = "00:00:00.000000"
       LAST_MICROSECOND = "23:59:59.999999"
@@ -663,7 +687,6 @@ module Hegel
       FORMAT = /\A(\d{2}):(\d{2}):(\d{2})\.(\d{6})\z/
 
       def initialize(min_value:, max_value:)
-        super()
         @min_value = min_value
         @max_value = max_value
       end
@@ -673,8 +696,10 @@ module Hegel
         max_parts = parse(@max_value || LAST_MICROSECOND, "max_value")
         raise Hegel::Error, "times: max_value < min_value" if (max_parts <=> min_parts).negative?
 
-        hour, minute, second, microsecond = tc.generate_time(min_parts, max_parts)
-        format("%02d:%02d:%02d.%06d", hour, minute, second, microsecond)
+        hour, minute, second, nanosecond = tc.generate_time(
+          Generators.first_nanosecond(min_parts), Generators.last_nanosecond(max_parts)
+        )
+        format("%02d:%02d:%02d.%06d", hour, minute, second, nanosecond / 1000)
       end
 
       private
@@ -682,7 +707,7 @@ module Hegel
       # +value+'s hour/minute/second/microsecond as an Array of Integers,
       # or raises if it is not a String matching FORMAT. This layer does
       # not range-check the parsed fields (an hour of 99, say): measured
-      # against libhegel 0.32.5, hegel_generate_time already returns
+      # against libhegel 0.45.0, hegel_generate_time already returns
       # HEGEL_E_INVALID_ARG for an invalid time, translated by
       # LibHegel.check! once #do_draw calls tc.generate_time, the same
       # division of labor DomainsGenerator follows for its own
@@ -713,15 +738,12 @@ module Hegel
     # converting to UTC first, so a caller who wants a specific wall-clock
     # bound does not have to convert it themselves.
     #
-    # Opens no span, for the same reason DatesGenerator does not (one
-    # native call, HEGEL_LABEL_DATETIME sits below HEGEL_LABEL_REGEX in the
-    # same header list).
+    # Opens no span, for the reason UuidsGenerator gives: one native call.
     class DatetimesGenerator < Generator
       MIN_DATETIME = Time.utc(1, 1, 1, 0, 0, 0, 0)
       MAX_DATETIME = Time.utc(9999, 12, 31, 23, 59, 59, 999_999)
 
       def initialize(min_value:, max_value:)
-        super()
         @min_value = min_value
         @max_value = max_value
       end
@@ -731,13 +753,18 @@ module Hegel
         max_value = @max_value || MAX_DATETIME
         raise Hegel::Error, "datetimes: max_value < min_value" if max_value < min_value
 
-        date, time = tc.generate_datetime(
+        # A drawn value has whole microseconds, so a bound with a fraction of
+        # one narrows to the whole microseconds inside the range. The lower
+        # bound rounds up, in its own zone; the upper bound's #usec below
+        # already drops its fraction.
+        min_value = min_value.ceil(6)
+        date, (hour, minute, second, nanosecond) = tc.generate_datetime(
           [min_value.year, min_value.month, min_value.day],
-          [min_value.hour, min_value.min, min_value.sec, min_value.usec],
+          Generators.first_nanosecond([min_value.hour, min_value.min, min_value.sec, min_value.usec]),
           [max_value.year, max_value.month, max_value.day],
-          [max_value.hour, max_value.min, max_value.sec, max_value.usec]
+          Generators.last_nanosecond([max_value.hour, max_value.min, max_value.sec, max_value.usec])
         )
-        Time.utc(*date, *time)
+        Time.utc(*date, hour, minute, second, nanosecond / 1000)
       end
     end
 
@@ -748,25 +775,23 @@ module Hegel
     # a draw surface (BlockTestCase below) and can call #draw on it any
     # number of times.
     #
-    # Spanned with HEGEL_LABEL_FLAT_MAP, not a label of its own: the header
-    # documents that label as the span around "a `flat_map` / monadic
-    # dependent draw", and a composite block is exactly that shape -- one
-    # or more draws, each free to depend on values the block already
-    # built, folded into a single result. No composite-specific label
-    # exists in the table this binding draws from (see lib_hegel.rb); if a
-    # true flat_map combinator is added later it can share this label, or
-    # the table can grow a dedicated one (hegel.h documents that a library
-    # may mint its own stable u64).
+    # One span goes around the block's draws. Its label names the block by
+    # where it is written, so two different composites do not share a
+    # label, the way hegel-rust's compose! labels each body by its source.
     class CompositeGenerator < Generator
       def initialize(&block)
-        super()
         @block = block
+        @label = LibHegel.label_combine(
+          [self.class.label, LibHegel.label_from_name(Array(@block&.source_location).join(":"))]
+        )
       end
 
+      attr_reader :label
+
       def do_draw(tc)
         raise Hegel::Error, "composite: block is required" unless @block
 
-        tc.start_span(LibHegel::HEGEL_LABEL_FLAT_MAP)
+        tc.start_span(label)
         begin
           @block.call(BlockTestCase.new(tc))
         ensure
@@ -829,7 +854,7 @@ module Hegel
     #
     # Opens no span: #do_draw makes no native call of its own, only
     # forwarding to whatever #set installed (one_of, above, already opens
-    # its own HEGEL_LABEL_ONE_OF span around that draw). This is the same
+    # its own span around that draw). This is the same
     # "a generator opens a span only around more than one native call it
     # makes itself" rule UuidsGenerator's own comment gives for a
     # generator that makes exactly one -- applied here to a generator that
@@ -838,7 +863,6 @@ module Hegel
     # Deferred) opens none either.
     class DeferredGenerator < Generator
       def initialize
-        super
         @inner = nil
       end
 
@@ -855,6 +879,14 @@ module Hegel
         @inner = generator
       end
 
+      # The installed generator's label, or this class's own before #set.
+      # A generator built from this one before #set keeps the class label,
+      # which is how a self-referential definition ends its own cycle, as
+      # hegel-rust's DeferredGenerator does.
+      def label
+        @inner ? @inner.label : self.class.label
+      end
+
       def do_draw(tc)
         raise Hegel::Error, "deferred: draw called before set" unless @inner