hegeltest 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd84332deb01b6efaed63023ba0f08d7515227f05eb5dc8e38e090b8a3ae59ad
-  data.tar.gz: 7a8139bea766f95a11188c57b71cd4f8006c448dd7fd4668aee6e269fe5ecb79
+  metadata.gz: 19a8534cce74c0577ca61891ead16d02d336efd87f3178a8672d6482bed4c6bb
+  data.tar.gz: 65a01d9c2400e3890cab677cb3ada046341305caa514f9d18ddd069f8e537fb3
 SHA512:
-  metadata.gz: 3689c4ec01d1999502205014194e864b02a968097041a56950534928f97361df2cf5ceb5550a78ada28138645bc4bb7b50973c3863bb28ba261b6cc61ac3cf70
-  data.tar.gz: 82a57b5fd774e5f75c6ccaff351caca2c21f9998bc1b01969c48a1f5984c965603e842d57ef42e375fd44edcd50e5b4ae03dfa34a1a6a37fe53247fbade5d465
+  metadata.gz: 9a2c433f9d32ba001b0c7667ce248ffebf8dab48c48a0655050cf80e8c0113305a0c957436ad510dca730b5b9b583ed99f3388cd959831765a10327310a4d7fb
+  data.tar.gz: 715fc4b8c0a810e09382593cd2d0eba009da5b78bd6747bb23fdd599bd6d89c8262ce6ab0d7e70b24c0067b6387c1b57ce3420e4b2c1863ce9392eb463561110

data/CHANGELOG.md

@@ -2,6 +2,264 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-21
+
+### Engine: libhegel 0.48.0 (was 0.47.2)
+
+The [libhegel 0.48.0 release notes](https://github.com/hegeldev/hegel/releases/tag/libhegel/0.48.0)
+describe 0.48.0.
+
+Each platform gem carries `libhegel` 0.48.0. The engine adds one function to
+its C interface, `hegel_set_unicode_version`, and changes no other function.
+These bindings do not call it yet, so the string generators continue to use
+the newest Unicode tables of the engine, as before. A caller has nothing to
+change in code. The engine move changes these results for a caller:
+
+- With the default `report_multiple_failures: false`, a run can find a
+  different, smaller failure while it shrinks the first one. The run now
+  shrinks that failure too before it reports it. In 0.47.2, the run reported
+  that failure without shrinking it.
+- `from_regex` accepts the end-of-string anchor `\z`. In 0.47.2, a pattern
+  with `\z` raised `Hegel::Error` with `HEGEL_E_INVALID_ARG`.
+- `floats(min_value: Float::INFINITY, allow_infinity: false)` and
+  `floats(max_value: -Float::INFINITY, allow_infinity: false)` leave no value
+  to draw. The draw now raises `Hegel::Error` with `HEGEL_E_INVALID_ARG` and
+  a message that contains "leaves no value". In 0.47.2, the draw raised
+  `Hegel::Error` with `HEGEL_E_INTERNAL`.
+
+### Profiles
+
+`Hegel.test` takes `profile:`, the name of a settings profile to start the
+run from: a shipped one, one in `hegel.toml`, or one you register. Left
+`nil`, the run starts from the default profile as before, and a keyword
+passed alongside still beats the profile.
+
+`Hegel::Settings.register_profile(name, profile: nil, **keywords)`
+registers a profile for the whole process, and
+`Hegel::Settings.set_default_profile(name)` makes a profile the default
+for every run; `""` clears it. They follow hegel-rust's
+`Settings::register_profile` and `set_default_profile`. An unknown or
+reserved name raises `Hegel::Error` with the engine's message. See
+[ADR 0028](docs/adr/0028-expose-settings-profiles-as-a-keyword-and-module-functions.md).
+
+### Settings
+
+`Hegel.test` takes five more keywords, with the names and meanings of
+hegel-rust's `Settings` methods. Each one left `nil` takes its value from
+the engine's settings profile, like `test_cases:` and `seed:`.
+
+- `stop_on_first_failure: false` keeps generating after a failure and
+  spends the whole `test_cases` budget before reporting.
+- `print_blob: false` leaves the `reproduce_failure:` line out of the
+  failure report. Left `nil`, a profile or `HEGEL_PRINT_BLOB` decides.
+- `show_statistics: true` makes the engine print, at the end of the run,
+  what `tc.event` and `tc.event_value` recorded.
+- `nondeterminism_strictness:` takes `:quiet`, `:warn`, or `:error`.
+  `:error` ends a run whose test behaves differently on a replay with
+  `Hegel::Error`.
+- `backend:` takes `:default` or `:urandom`.
+
+### Test location
+
+Every `Hegel.test` run now reports where its test lives to libhegel, with
+`hegel_settings_set_test_location`. Under Antithesis the engine writes one
+`always` assertion, "<class>::<function> passes properties", for each
+location; elsewhere it uses nothing, and no keyword changes. The file is
+relative to the working directory when it lies under it, and the class and
+function come from the frame that called `Hegel.test`. A call inside a
+block takes the name of the method holding the block, and a call outside
+any method, such as an RSpec example, takes the file without `.rb` as the
+class and `line <n>` as the function, so each example in a file has its
+own name.
+
+### Test cases
+
+`tc.event(label)` and `tc.event_value(label, value)` record what a test
+reached, for the statistics that `show_statistics: true` prints. They follow
+hegel-rust's `TestCase#event` and `TestCase#event_value`.
+
+### Generators
+
+- `date_strings`, `time_strings`, and `datetime_strings` generate ISO 8601
+  date, time, and datetime Strings, with no options, as hegel-rust does.
+  A time keeps nanoseconds: nine fractional digits appear when the
+  nanosecond is not zero.
+- `permutations`, `subsequences`, and `samples` draw reorderings, ordered
+  subsets, and samples of a given sequence, as hegel-rust does. Its
+  `with_replacement` and `without_replacement` setters are one keyword here,
+  `samples(replacement: true)`, which is the default.
+- `durations(min_value: 0, max_value: 2**64 - 1)` draws a duration as an
+  `Integer` count of nanoseconds, as hegel-rust's `durations` does for a
+  `Duration`. It follows [ADR 0030](docs/adr/0030-represent-a-duration-as-integer-nanoseconds.md).
+- `arrays(elements, unique: true)` draws an array with no two equal entries,
+  as hegel-rust's `vecs(...).unique(true)` does. An element equal to one
+  already drawn is rejected and drawn again, so `min_size` still counts
+  distinct entries.
+- `floats(allow_subnormal: nil)` allows or rules out subnormal values, as
+  hegel-rust's `allow_subnormal` does. Left `nil`, it allows them whenever
+  the bounds admit one. A `floats` call whose bounds admit none, such as
+  `floats(min_value: 1.0, max_value: 2.0)`, now tells the engine so.
+- `recursive(leaf, max_depth: 32, max_leaves: 100) { |subtrees| ... }`
+  draws a recursively defined value, such as a tree, through the engine's
+  recursion calls, as hegel-rust's `recursive` does. The engine decides each
+  leaf-or-branch choice and owns both budgets. An attempt that outgrows
+  `max_leaves` is drawn again from the root, and the spans it opened are
+  discarded, not kept. See
+  [ADR 0032](docs/adr/0032-suppress-span-closes-while-an-abandoned-recursion-attempt-unwinds.md).
+
+### Text generators
+
+`text` and `characters` take `categories:`, `exclude_categories:`,
+`include_characters:`, and `exclude_characters:`, with the names hegel-rust
+gives them. `text` also takes `alphabet:`, a `String` of the permitted
+characters, and raises `Hegel::Error` at draw
+time when it is combined with another character option. `from_regex` takes
+`alphabet:`, a `characters` generator that limits every character of the
+string, padding included. An unknown `codec:` now raises `"text: invalid
+codec: ..."` (or `characters:`) before the engine is called, and a
+surrogate category in `categories:` raises too.
+
+### Grammar strings
+
+`from_lark(grammar)` draws strings that a grammar written in the syntax of
+the [Lark](https://lark-parser.readthedocs.io/en/stable/grammar.html)
+parsing library accepts, as hegel-rust's `from_lark` does. It takes
+`start:`, `explicit:` (a `Hash` from terminal name to a generator of the
+values drawn for it), `alphabet:` (a `characters` generator),
+`max_size:`, `max_depth:`, and `import_path:`. An invalid option raises
+`Hegel::Error` at draw time, with hegel-rust's message where it has one.
+A grammar is compiled on its first draw in a run and freed when the run
+ends.
+
+### Added
+
+- `rule(name, weight: 1.0)` sets how often the engine picks a rule relative to
+  the machine's other rules, as `#[rule(weight = w)]` does in hegel-rust. A
+  weight that is not finite and positive raises `Hegel::Error` when the machine
+  runs. `Hegel::StateMachine.rule_definitions` now maps each name to a
+  `Hegel::StateMachine::Rule` with `block` and `weight`, where it mapped to the
+  block alone.
+
+### Fixed
+
+- A filter on `Pool#values_consumed` no longer loses the values it rejects. They
+  go back into the pool through `hegel_pool_restore` once the draw is over, and
+  only the accepted value is consumed, as in hegel-rust.
+
+### Changed
+
+Three defaults now match hegel-rust, which defines the interface. The results
+change for a caller who relied on the old default.
+
+- `from_regex` defaults to `fullmatch: true`, where it was `false`. The whole
+  drawn string matches the pattern, instead of merely containing a match. To
+  keep the old behaviour, pass `fullmatch: false`.
+- `text` defaults `max_size` to 100, where it was unbounded. When `min_size`
+  is above 100, the default is `min_size + 100`. Strings drawn without a
+  `max_size` are shorter than before. To draw longer strings, pass the
+  larger `max_size` you need.
+- `binary` defaults `max_size` the same way, to 100 or `min_size + 100`.
+
+- A filter over a filter now spends 3 attempts between the two predicates, as
+  hegel-rust does, where each level used to spend 3 of its own.
+- `Hegel::Generator#do_draw_filtered(tc, predicate)` is the draw behind
+  `#filter`. A generator whose draws have effects that a rejected value must
+  not keep overrides it.
+
+### Repeat a test body
+
+`tc.repeat { ... }` runs its block again and again, for as long as the
+engine keeps the loop going, the way hegel-rust's `TestCase::repeat` does.
+The engine chooses how many times it runs, and shrinks a failure toward
+fewer iterations. Each iteration shows in the failure report as a
+`// Repetition #N` line, with what the iteration recorded indented under
+it. A `tc.assume` or `tc.reject` inside the block skips that iteration
+instead of discarding the whole test case.
+
+The loop does not return when it ends. It raises `Hegel::LoopDone`, which
+`Hegel.test` counts as a passing test case. It descends from `Exception`,
+like the other control exceptions, so a `rescue => e` in the body does not
+catch it. A `break` in the block ends the loop and returns from
+`tc.repeat`. See
+[ADR 0034](docs/adr/0034-repeat-a-test-body-with-a-ruby-side-indent.md).
+
+## [0.3.4] - 2026-10-20
+
+### Engine: libhegel 0.47.2 (was 0.47.1)
+
+The [libhegel 0.47.2 release notes](https://github.com/hegeldev/hegel/releases/tag/libhegel/0.47.2)
+describe 0.47.2. It is the first engine release from the hegeldev/hegel
+repository.
+
+Each platform gem carries `libhegel` 0.47.2. The engine does not change its
+C interface. A caller has nothing to change in code, and gets the same
+results. The engine changes one text: the message of an internal engine
+error now gives <https://github.com/hegeldev/hegel/issues> as the place to
+report the problem, not the hegel-rust issue tracker.
+
+### Development
+
+- `rake libhegel:fetch` and `rake libhegel:fetch_all` download libhegel
+  0.47.2 and later from the hegeldev/hegel releases, and earlier versions
+  from the hegeldev/hegel-rust releases.
+
+## [0.3.3] - 2026-10-17
+
+### Engine: libhegel 0.47.1 (was 0.45.13)
+
+The [libhegel 0.47.1 release notes](https://github.com/hegeldev/hegel-rust/releases/tag/libhegel-v0.47.1)
+describe 0.47.1 alone. The
+[engine changelog](https://github.com/hegeldev/hegel-rust/blob/libhegel-v0.47.1/hegel-c/CHANGELOG.md)
+describes each engine release after 0.45.13, up to 0.47.1.
+
+Each platform gem carries `libhegel` 0.47.1. The engine changes its C
+interface: every string is now a `hegel_string_t`, a pointer and a length.
+These bindings follow that change. A caller has nothing to change in code.
+The engine move changes these results for a caller:
+
+- A run with the default `report_multiple_failures: false` that finds more
+  than one distinct failure shrinks only the smallest of them and reports
+  it. Before, the engine shrank each failure and then reported one. The
+  example database keeps every distinct failure, as found. Such a run calls
+  the test body fewer times: for a body with two distinct failures and
+  `test_cases: 100`, 73 to 131 calls over 20 seeded runs, where 0.45.13
+  made 157 to 202. Both versions reported the same failure in each run.
+- A string that holds a NUL character, such as a `target` label or a
+  `database:` path, reaches the engine whole. Before, it raised
+  `ArgumentError` ("string contains null byte") from the `ffi` gem.
+
+## [0.3.2] - 2026-10-16
+
+### Engine: libhegel 0.45.13 (was 0.45.7)
+
+The [libhegel 0.45.13 release notes](https://github.com/hegeldev/hegel-rust/releases/tag/libhegel-v0.45.13)
+describe 0.45.13 alone. The
+[engine changelog](https://github.com/hegeldev/hegel-rust/blob/libhegel-v0.45.13/hegel-c/CHANGELOG.md)
+describes each engine release after 0.45.7, up to 0.45.13.
+
+Each platform gem carries `libhegel` 0.45.13. The engine only adds to its C
+interface, and these bindings do not use the addition. A caller has nothing
+to change in code. The engine changes these results for a caller:
+
+- A run with a `seed:` can draw different values than it did before. The
+  engine changed how it copies values between spans that have the same
+  label, and how it draws an integer from a range wider than 128 bits.
+- A failure that depends on an integer that is a multiple of a number, such
+  as 6, shrinks to the smallest such value more often. Before, the shrinker
+  could stop at a larger multiple, such as 78.
+- A run of 1,000 test cases or more starts to use `target` scores soon
+  after it starts. Before, it started after half of the test cases.
+- The `note:` line with the engine's nondeterminism caveat shows only for a
+  failure that the engine saw pass at least one time. Before, every failure
+  of a run that the engine treated as nondeterministic showed it.
+- `reproduce_failure:` stops a replay when the test body draws differently
+  from the recorded choices. If no replay reproduces the failure, the run
+  raises `Hegel::Error` with the message that says that the blob did not
+  reproduce a failure, and the engine writes one line to standard error
+  that names the position where the draws left the recorded choices.
+  Before, the engine continued the replay with new draws and could report a
+  different failure as the failure of the blob.
+
 ## [0.3.1] - 2026-10-15
 
 ### Engine: libhegel 0.45.7 (was 0.45.4)
@@ -196,6 +454,10 @@ The engine is called through the `ffi` gem. Each platform gem carries the
 matching `libhegel` 0.32.5 build. The platform-independent gem carries none,
 so a run on it needs `HEGEL_LIBHEGEL_PATH` pointing at a local build.
 
+[0.4.0]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.4.0
+[0.3.4]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.3.4
+[0.3.3]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.3.3
+[0.3.2]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.3.2
 [0.3.1]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.3.1
 [0.3.0]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.3.0
 [0.2.1]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.2.1