hegeltest 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: facbe6e366b74782ab68e979295856ef15c8da56ea9d9fe9291764cbf1629eb3
-  data.tar.gz: e78e0364232dc02974f7ca81135a34325a76287c425d59f1d384ef2f2acfb2aa
+  metadata.gz: 5979893a1e1ad319ad6526c5f2ad6927961084c40006946c3f4e0d3bb6a9f269
+  data.tar.gz: b5c146a01b94e5832fac50b42c983c844a3b494849038c6776ae54d7fb23a787
 SHA512:
-  metadata.gz: c977d4fd78f3439b18b731ae14c6772968aff53271fe1f44a8712f044a6dc0bcdcbd0ece18da677a7e3599a831651806a979c6985d5b942e6d89534c5c6eae14
-  data.tar.gz: 429fb8e7ce09f224c32368ad0d34bc69d1020f56891bdb2616da02acb86fa0ef5c174f340f27fc5a0cdf4918e8a4f82075781128850656b571e0b4232143abf5
+  metadata.gz: 7f0d698a9810abb8c3c2d68e38ad947386948ca840d59339962378db721cd8a961009ce7a68d69577b0aed240fbc80d84b635971c2810bcd0cf827eed6a6368d
+  data.tar.gz: 111d8e783b4236b9b5105819b9b34e96d2bbb1a0c314a25dc6f093903e0652bedad4d70d9c8951c865e3bcdeb1947c67f425668b599bffce79c6825468c3ce3e

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.1.1] - 2026-08-31
+
+The reference that ships inside the gem told a reader to install `hegeltest`
+from git and to point `HEGEL_LIBHEGEL_PATH` at a local build. 0.1.0 shipped
+that text, and 0.1.0 needs neither. A reader who followed it spent their first
+minutes on a checkout and an engine build. The reference now says what the
+README says.
+
+A drawn value written inside a larger expression named itself after the
+assignment target, so `term_start_date = Date.new(tc.draw(...), 2, 29)`
+reported `term_start_date` beside a year. Such a draw now takes the generic
+name, and `label:` names it when a name is wanted. See
+[ADR 0014](docs/adr/0014-name-a-drawn-value-only-when-the-draw-is-the-whole-assigned-value.md).
+
+The settings table names 100 as libhegel's own default for `test_cases`. The
+README shows how to scope `Hegel::Syntax::Methods` to tagged example groups in
+a suite that already exists, and how to share a group of draws through a plain
+Ruby method. The `text` section says which generators cover the character-set
+options it does not take, measured against libhegel 0.32.5.
+
 ## [0.1.0] - 2026-08-20
 
 The first release.
@@ -19,4 +39,5 @@ 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.1.1]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.1.1
 [0.1.0]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.1.0

data/README.md

@@ -31,8 +31,7 @@ same process. There is no server and no Python dependency.
 
 ## Status
 
-**The first release is prepared, and the version is `0.1.0`.** Everything
-described below runs: Hegel finds a counterexample, shrinks it,
+**Released as `hegeltest` 0.1.0.** Hegel finds a counterexample, shrinks it,
 names the values it drew, and re-raises your own exception.
 
 Work ran in three stages, and all three are done:
@@ -44,22 +43,18 @@ Work ran in three stages, and all three are done:
 3. **The advanced features**: the example database, targeted testing,
    stateful testing, phases, and health checks.
 
-**Nothing is published to RubyGems yet.** The packaging is built:
-`rake platform_gems:build` produces one gem per platform, each carrying the
-matching `libhegel` build. The arm64 macOS gem is verified to find that
-engine inside itself and run a property with no `HEGEL_LIBHEGEL_PATH` set.
-A `v*` tag publishes all six gems from CI. The Hegel maintainers permit a
-third-party project to redistribute their release binaries
-([hegeldev/hegel-rust#411]).
-
-So running this today means cloning the repository:
+Install it the way you install any gem:
 
-```bash
-bin/setup
-bundle exec rake libhegel:fetch   # downloads the pinned build, checked against its SHA-256
-bundle exec rake
+```ruby
+# Gemfile
+gem "hegeltest"
 ```
 
+Each platform gem carries the matching `libhegel` build, so an install
+compiles nothing and needs no engine on the side. The Hegel maintainers
+permit a third-party project to redistribute their release binaries
+([hegeldev/hegel-rust#411]).
+
 Every push to main runs the suite on Ruby 3.3, 3.4, and 4.0, across Linux x64
 and arm64, macOS arm64, and Windows x64 and arm64. Windows arm64 starts at
 Ruby 3.4, the oldest Ruby that RubyInstaller publishes an arm64 build for. A
@@ -79,13 +74,13 @@ pull request runs Linux x64 alone.
 | Platforms | Linux amd64/arm64, macOS arm64, Windows amd64/arm64 |
 | Engine delivery | One prebuilt `libhegel` per platform-specific gem, built by `rake platform_gems:build` |
 
-`HEGEL_LIBHEGEL_PATH` will override the bundled engine with a local build.
+`HEGEL_LIBHEGEL_PATH` overrides the bundled engine with a local build.
 
 The gem name follows the Rust implementation, whose published crate is
 `hegeltest` and whose library is `hegel`. The name `hegel` on RubyGems.org
 stays free for whoever publishes an official Ruby implementation.
 
-macOS on Intel has no published `libhegel` artifact, so that platform will need
+macOS on Intel has no published `libhegel` artifact, so that platform needs
 `HEGEL_LIBHEGEL_PATH` and a local build.
 
 ## Quickstart
@@ -135,6 +130,33 @@ Including `Hegel::Syntax::Methods` makes the generators available without a
 prefix, the way FactoryBot makes `create` available. The same generators stay
 reachable as `Hegel::Generators.arrays(...)` without the include.
 
+An existing RSpec suite can limit the 25 generator names to tagged example
+groups. This keeps the names out of other groups that have their own helpers:
+
+```ruby
+config.include Hegel::Syntax::Methods, :hegel
+```
+
+A new project can include the methods in every group, as the Quickstart does.
+
+Hegel draws values imperatively, so an ordinary Ruby method can share a group
+of draws between properties. Give the method parameter a descriptive name,
+which the default RuboCop naming rule accepts where a block parameter `tc`
+needs no change:
+
+```ruby
+def draw_sorted_pair(test_case)
+  low = test_case.draw(integers(min_value: 0, max_value: 100))
+  high = test_case.draw(integers(min_value: low, max_value: 200))
+  [low, high]
+end
+
+Hegel.test do |tc|
+  low, high = draw_sorted_pair(tc)
+  expect(low).to be <= high
+end
+```
+
 The generators are `arrays`, `binary`, `booleans`, `characters`, `composite`,
 `dates`, `datetimes`, `deferred`, `domains`, `emails`, `floats`, `from_regex`,
 `hashes`, `integers`, `ip_addresses`, `just`, `one_of`, `optional`,
@@ -241,9 +263,10 @@ Inside a test, `tc.note` records a message the failure report prints, and
 ## Development
 
 ```bash
-bin/setup          # install dependencies
-bundle exec rake   # run the tests and the linter
-bin/console        # open an interactive prompt
+bin/setup                        # install dependencies
+bundle exec rake libhegel:fetch  # download the pinned engine, checked against its SHA-256
+bundle exec rake                 # run the tests and the linter
+bin/console                      # open an interactive prompt
 ```
 
 `just` recipes call the same Rake tasks, so `just test` and `just lint` work

data/docs/README.md

@@ -20,6 +20,7 @@ An index of the design records for `hegel-ruby`.
 - [0011: Let the test case own every pool drawn from it](adr/0011-let-the-test-case-own-every-pool-drawn-from-it.md)
 - [0012: Build a failure origin from the caller's own frame](adr/0012-build-a-failure-origin-from-the-callers-own-frame.md)
 - [0013: Bind libhegel through the ffi gem](adr/0013-bind-libhegel-through-the-ffi-gem.md)
+- [0014: Name a drawn value only when the draw is the whole assigned value](adr/0014-name-a-drawn-value-only-when-the-draw-is-the-whole-assigned-value.md)
 
 A new decision gets a new record. A changed decision supersedes the old
 record instead of editing it, so the history stays readable.

data/docs/adr/0014-name-a-drawn-value-only-when-the-draw-is-the-whole-assigned-value.md

@@ -0,0 +1,74 @@
+# 0014: Name a drawn value only when the draw is the whole assigned value
+
+## Status
+
+Accepted.
+
+## Context
+
+[ADR 0005](0005-name-drawn-values-from-the-callers-source-with-prism.md)
+recovers a drawn value's name by parsing the caller's source and reading the
+assignment that covers the draw's line. Its Consequences section lists three
+cases it had not checked: a heredoc, several draws on one line, and a method
+chain.
+
+A first use of the gem outside this repository reached one of them. The
+caller wrote a draw inside a larger expression:
+
+```ruby
+term_start_date = Date.new(tc.draw(integers(min_value: 1904, max_value: 1904)), 2, 29)
+```
+
+Measured against libhegel 0.32.5, the failure report printed:
+
+```
+term_start_date = 1904
+```
+
+The name says "a date". The value is a year. The reader misread that report
+twice before adding a `label:`.
+
+`Hegel::DrawName` already carries the rule this breaks. Its own
+documentation states it: a wrong name misdirects a reader of the failure
+report more than a missing one does, so an ambiguous line returns nil rather
+than choosing between candidates. The module applied that rule to two
+assignments written side by side, and applied the opposite rule to a draw
+buried in one assignment's value.
+
+A draw pulled out into a plain method is a separate case, and it already
+worked. Measured on the same engine, a helper whose body reads
+`year = tc.draw(integers(min_value: 1900, max_value: 1910))` reported
+`year = 1900`. `Hegel::TestCase::DRAW_CALLER_DEPTH` lands on the line that
+called the draw, which is the helper's own line, and the name there is the
+one the caller wrote.
+
+## Decision
+
+Recover a name only when the assignment's value is the draw call itself: the
+value node is a `Prism::CallNode` whose name is one of the methods that reach
+`Hegel::TestCase#record_draw`. Any other value node returns nil, and
+`Hegel::TestCase#name_for` falls back to the generic name.
+
+The three method names stay in `Hegel::TestCase`, which defines them, and
+`Hegel::DrawName.for` takes them as an argument. A fourth draw method then
+has one place to be added.
+
+## Consequences
+
+A draw written inside a larger expression reports the generic name and its
+value. The reader loses a name and keeps a value that agrees with it. A
+caller who wants the name back passes `label:`, which
+[ADR 0005](0005-name-drawn-values-from-the-callers-source-with-prism.md)
+already gives precedence over the recovered name.
+
+A method chain answers the question ADR 0005 left open, and answers it the
+same way: `xs = tc.draw_integer(0, 10).to_s` reports the generic name,
+because `xs` holds a String and the drawn value is an Integer.
+
+A draw written inside another draw's arguments shares the enclosing
+assignment's name, because the enclosing assignment's value is a draw call
+and one line carries both draws. `label:` separates them.
+
+`Hegel::DrawName` now answers a narrower question than its name suggests on
+its own, so its documentation states the question it answers and the reason
+for the narrowing.

data/lib/hegel/draw_name.rb

@@ -6,9 +6,10 @@ module Hegel
   # Recovers a drawn value's variable name from the caller's own source (see
   # docs/adr/0005), so a failure report can print `n = 501` instead of
   # `draw = 501` when the caller never passed a label:. This module only
-  # answers "what name does path:lineno assign a value to"; deciding
-  # whether to call it, and what to fall back to when it answers nil, is
-  # Hegel::TestCase#name_for's job, not this one's.
+  # answers "what name does path:lineno assign the value a draw call there
+  # produced, when that call is the whole assigned value"; deciding whether
+  # to call it, what counts as a draw call, and what to fall back to when it
+  # answers nil, is Hegel::TestCase#name_for's job, not this one's.
   module DrawName
     # Node types #for treats as "this line names a drawn value". An
     # explicit list, not every Prism::Node subclass whose name ends in
@@ -23,10 +24,20 @@ module Hegel
 
     # The name +path+:+lineno+ assigns a drawn value to, or nil when that
     # cannot be answered confidently: +path+ cannot be read, Prism cannot
-    # parse it, or the assignments covering +lineno+ do not single one out.
+    # parse it, the assignments covering +lineno+ do not single one out, or
+    # the one they single out does not assign a draw call directly.
+    # +call_names+ is the set of method names that count as a draw call
+    # (Hegel::TestCase::DRAW_METHOD_NAMES); this module has no opinion of
+    # its own about which methods draw.
+    #
     # A wrong name would misdirect a reader of the failure report more than
     # a missing one would, so an ambiguous line returns nil rather than
-    # guessing between candidates.
+    # guessing between candidates. That is also why a singled-out
+    # assignment still answers nil when its value is built from a draw
+    # rather than being the draw itself, as in `xs = [tc.draw(integers)]`
+    # or `n = tc.draw(integers).abs`: the recovered name would describe the
+    # Array or the Integer#abs result, not the drawn value the report
+    # actually prints next to it.
     #
     # Several assignments can cover one line by nesting rather than by
     # ambiguity. `error = assert_raises do ... n = tc.draw_integer(...) ...
@@ -35,13 +46,16 @@ module Hegel
     # whenever another candidate sits inside it. Two assignments written
     # side by side on one line contain neither the other, nothing singles
     # one out, and the answer is nil.
-    def for(path, lineno)
+    def for(path, lineno, call_names)
       program = parse(path)
       return nil unless program
 
       matches = assignment_nodes(program).select { |node| covers?(node.location, lineno) }
       innermost = matches.reject { |node| matches.any? { |other| encloses?(node, other) } }
-      innermost.one? ? innermost.first.name.to_s : nil
+      return nil unless innermost.one?
+
+      node = innermost.first
+      (node.value.is_a?(Prism::CallNode) && call_names.include?(node.value.name)) ? node.name.to_s : nil
     end
 
     # Drops every cached parse. #for's only state; a fresh process would

data/lib/hegel/test_case.rb

@@ -25,6 +25,12 @@ module Hegel
     # #name_for's fallback when a draw has no better name (see below).
     DEFAULT_DRAW_NAME = "draw"
 
+    # The method names that reach #record_draw: #draw_integer, #draw_boolean,
+    # and #draw below. Hegel::DrawName.for takes this as an argument rather
+    # than knowing the list itself, so that class -- not DrawName -- stays
+    # the one place a fourth draw method needs to be added.
+    DRAW_METHOD_NAMES = [:draw, :draw_integer, :draw_boolean].freeze
+
     # Frames from #name_for's own caller_locations call up to the user's own
     # source line: #record_draw's call to #name_for (1), the public
     # draw_integer/draw_boolean/draw call to #record_draw (2), and the
@@ -517,7 +523,7 @@ module Hegel
       return label if label
 
       location = caller_locations(depth, 1)&.first
-      (location && DrawName.for(location.path, location.lineno)) || DEFAULT_DRAW_NAME
+      (location && DrawName.for(location.path, location.lineno, DRAW_METHOD_NAMES)) || DEFAULT_DRAW_NAME
     end
   end
 end

data/lib/hegel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hegel
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/sig/hegel.rbs

@@ -17,6 +17,7 @@ module Hegel
 
   class TestCase
     DEFAULT_DRAW_NAME: String
+    DRAW_METHOD_NAMES: Array[Symbol]
     DRAW_CALLER_DEPTH: Integer
 
     def initialize: (untyped impl, untyped ctx, untyped handle, ?record: bool) -> void
@@ -326,7 +327,7 @@ module Hegel
   module DrawName
     ASSIGNMENT_NODE_TYPES: Array[untyped]
 
-    def self.for: (String path, Integer lineno) -> String?
+    def self.for: (String path, Integer lineno, Array[Symbol] call_names) -> String?
     def self.reset_cache: () -> void
     def self.parse: (String path) -> untyped
     def self.cache: () -> Hash[String, untyped]

data/skills/hegel-ruby/references/ruby/reference.md

@@ -13,16 +13,18 @@
 
 ## Setup
 
-Hegel for Ruby is packaged as the `hegeltest` gem, which has not reached
-RubyGems.org yet. Installing it from git works for the Ruby code. A git
-checkout carries no `libhegel` engine, so a run also needs
-`HEGEL_LIBHEGEL_PATH` pointing at a local build:
+Hegel for Ruby is packaged as the `hegeltest` gem. Each platform gem carries
+the matching `libhegel` engine, so an install compiles nothing and needs no
+engine on the side:
 
 ```ruby
 # Gemfile
-gem "hegeltest", git: "https://github.com/meganemura/hegel-ruby"
+gem "hegeltest"
 ```
 
+A platform with no published `libhegel` build, such as macOS on Intel, needs
+`HEGEL_LIBHEGEL_PATH` pointing at a local build instead.
+
 Require it, then include the generator methods wherever tests draw values:
 
 ```ruby
@@ -127,7 +129,7 @@ end
 
 | Keyword | Type | Default | Purpose |
 |---|---|---|---|
-| `test_cases` | `Integer` or `nil` | `nil` (libhegel's own default) | Number of test cases to run |
+| `test_cases` | `Integer` or `nil` | `nil` (libhegel's own default: 100) | Number of test cases to run |
 | `seed` | `Integer` or `nil` | `nil` (libhegel picks its own) | Fixed RNG seed; pair with `derandomize: true` for a reproducible sequence |
 | `derandomize` | `true`/`false` or `nil` | `nil` (libhegel's own default) | Derive the seed deterministically from the test itself, instead of drawing a random one |
 | `verbosity` | `Symbol` or `nil` | `nil` (libhegel's own default) | `:quiet`, `:normal`, `:verbose`, or `:debug` |
@@ -273,6 +275,22 @@ To reproduce this failure, pass the blob below to Hegel.test:
     reproduce_failure: "AAEAAAAACgEAAAAG"
 ```
 
+An ordinary Ruby method can share a related group of draws. Use a descriptive
+method parameter name so that the default RuboCop naming rule accepts it:
+
+```ruby
+def draw_sorted_pair(test_case)
+  low = test_case.draw(integers(min_value: 0, max_value: 100))
+  high = test_case.draw(integers(min_value: low, max_value: 200))
+  [low, high]
+end
+
+Hegel.test do |tc|
+  low, high = draw_sorted_pair(tc)
+  raise "values are out of order" unless low <= high
+end
+```
+
 `assume` discards a test case (the same way `reject` does) unless its
 condition holds, read as ordinary Ruby truthiness rather than restricted to
 `true`/`false`, so `tc.assume(hash[:key])` works directly:
@@ -450,6 +468,39 @@ min_size"`. `alphabet:`, `categories:`, `include_characters:`, and
 expose) are not available in this binding; `codec:`, `min_codepoint:`, and
 `max_codepoint:` are the alphabet controls it exposes today.
 
+Other generators cover most character-set jobs. These results were measured
+with libhegel 0.32.5 on this repository's main branch:
+
+| Job | Generator | Measured output |
+|---|---|---|
+| Characters to include | `from_regex("[ぁ-んA-Z0-9]{1,5}", fullmatch: true)` | `"げLだづは"`, `"あぐA"` |
+| Characters to exclude | `from_regex("[^,\\t\\n]{0,6}", fullmatch: true)` | `"Ë3ù*掆&"`, `"MßzæŜ\u0002"`; 30 draws contained no comma, tab, or newline |
+| A contiguous block | `text(min_codepoint: 0x300, max_codepoint: 0x36F)` | Every character was in U+0300 through U+036F |
+| An arbitrary alphabet | `arrays(sampled_from(%w[ß a İ]), max_size: 4).map(&:join)` | `"İaİß"`, `"ßßß"` |
+
+The `categories:` option remains an open request. A category such as any `Lu`
+or any `Mn` spans codepoint ranges that a codepoint bound cannot select. A
+regular expression character class requires those ranges to be written out.
+The `.filter` method is not a substitute. In a measured run of 50 test cases,
+filtering `text` to `\p{Han}` produced no valid inputs. The engine filtered 50
+inputs and reported this health check:
+
+```
+FailedHealthCheck: FilterTooMuch — it looks like this test is filtering out
+too many inputs. 50 inputs were filtered out by assume() while only 0 valid
+inputs were generated. If this is expected, suppress the check with
+suppress_health_check = [HealthCheck::FilterTooMuch].
+```
+
+The engine writes that last sentence in its own naming. This binding takes
+the same setting as `suppress_health_check: [:filter_too_much]`, listed in
+[Settings](#settings).
+
+Unconfigured `text` draws from a much wider Unicode range. In 200 draws of
+`text(min_size: 1, max_size: 4)`, the results included emoji, private-use
+characters, and control characters. The highest codepoint was U+10F11A. A
+property that accepts any string needs no character-set options.
+
 ### `arrays(elements, min_size: 0, max_size: nil)`
 
 An `Array` of values from the `elements` generator, with `[min_size,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hegeltest
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - meganemura
@@ -59,6 +59,7 @@ files:
 - docs/adr/0011-let-the-test-case-own-every-pool-drawn-from-it.md
 - docs/adr/0012-build-a-failure-origin-from-the-callers-own-frame.md
 - docs/adr/0013-bind-libhegel-through-the-ffi-gem.md
+- docs/adr/0014-name-a-drawn-value-only-when-the-draw-is-the-whole-assigned-value.md
 - docs/architecture.md
 - lib/hegel.rb
 - lib/hegel/draw_name.rb