zizek 0.1.0

data/examples/multi.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Port of Hegel's two-assertion example. Zizek reports the first failure found
+# and preserves that assertion site while shrinking, so a candidate which trips
+# the other assertion cannot be mistaken for progress on the selected bug.
+
+require "zizek"
+
+module MultiExample
+  EDGE = 1_337
+
+  module_function
+
+  def property(test_case)
+    value = test_case.draw(
+      Zizek::Generators.integers.min_value(0).max_value(2_000)
+    )
+    raise "#{value} hit the forbidden edge" if value == EDGE
+    raise "#{value} is not below the edge" unless value < EDGE
+  end
+
+  def find_and_replay_one_origin
+    found =
+      begin
+        Zizek.check(method(:property), examples: 100, seed: 1)
+        raise "one of the two integer bugs should be discovered"
+      rescue Zizek::Failure => failure
+        message = failure.property_cause.message
+        unless message.include?("forbidden edge") || message.include?("not below the edge")
+          raise "unexpected failure origin: #{message}"
+        end
+        failure
+      end
+
+    begin
+      Zizek.check(method(:property), reproduce: found.blob)
+    rescue Zizek::Failure => replayed
+      raise unless replayed.property_cause.message == found.property_cause.message
+
+      return found
+    end
+    raise "the selected failure origin must replay"
+  end
+end
+
+puts MultiExample.find_and_replay_one_origin if $PROGRAM_NAME == __FILE__

data/examples/queue.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Model-based stateful example: a bounded ring queue vs a plain array model.
+#
+# Demonstrates:
+#   - manual state machines (Zizek::Stateful::Rule, Zizek::Stateful.run);
+#   - assumptions inside rules (pop is rejected while the queue is empty);
+#   - invariants checked after every successful rule;
+#   - failure capture — the bug eventually reads past the backing array; and
+#   - structural shrinking of whole rule spans plus blob replay.
+
+require "zizek"
+
+module QueueExample
+  CAPACITY = 2
+
+  # The shrunk failure blob is identical in Go, Python, and Ruby.
+  PORTABLE_QUEUE_FAILURE =
+    "AXicjcnBCQBACAPB3e8VcP2XqiL4E8xnQvIB5UmlcYrbkp7ONAAiJQCa"
+
+  # A fixed-capacity FIFO queue over a circular buffer. Pop wraps the head
+  # index one slot too late — a deliberate off-by-one that reads past the
+  # backing array (returning nil) on the third pop.
+  class RingQueue
+    attr_reader :size
+
+    def initialize
+      @data = Array.new(CAPACITY, 0)
+      @head = 0
+      @tail = 0
+      @size = 0
+    end
+
+    def push(value)
+      return false if size == CAPACITY
+
+      @data[@tail] = value
+      @tail = (@tail + 1) % CAPACITY
+      @size += 1
+      true
+    end
+
+    def pop
+      value = @data[@head]
+      @head = (@head + 1) % (CAPACITY + 1) # BUG: should wrap modulo CAPACITY
+      @size -= 1
+      value
+    end
+  end
+
+  class QueueTest
+    def initialize
+      @queue = RingQueue.new
+      @model = []
+    end
+
+    def push(test_case)
+      value = test_case.draw(Zizek::Generators.integers.min_value(0).max_value(99))
+      if @queue.push(value)
+        @model << value
+        test_case.note("push #{value}")
+      else
+        test_case.note("push #{value} refused: queue full")
+      end
+    end
+
+    def pop(test_case)
+      test_case.assume(!@model.empty?)
+      want = @model.shift
+      got = @queue.pop
+      test_case.note("pop -> #{got.inspect}")
+      raise "pop returned #{got.inspect}, expected #{want}" unless got == want
+    end
+
+    def sizes_agree(_test_case)
+      return if @queue.size == @model.length
+
+      raise "queue reports #{@queue.size} items, model holds #{@model.length}"
+    end
+
+    def rules
+      [
+        Zizek::Stateful::Rule.new("push", ->(machine, test_case) { machine.push(test_case) }),
+        Zizek::Stateful::Rule.new("pop", ->(machine, test_case) { machine.pop(test_case) })
+      ]
+    end
+
+    def invariants
+      [
+        Zizek::Stateful::Rule.new(
+          "sizes_agree",
+          ->(machine, test_case) { machine.sizes_agree(test_case) }
+        )
+      ]
+    end
+  end
+
+  module_function
+
+  def property(test_case)
+    Zizek::Stateful.run(QueueTest.new, test_case)
+  end
+
+  def find_and_replay_bug
+    found =
+      begin
+        Zizek.check(method(:property), examples: 2_000, seed: 3)
+        raise "the ring-queue off-by-one should be discovered"
+      rescue Zizek::Failure => failure
+        failure
+      end
+
+    begin
+      Zizek.check(method(:property), reproduce: found.blob)
+    rescue Zizek::Failure
+      return found
+    end
+    raise "the shrunk queue failure must replay"
+  end
+end
+
+puts QueueExample.find_and_replay_bug if $PROGRAM_NAME == __FILE__

data/examples/roundtrip.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Round-trip property example: run-length encoding.
+#
+# Demonstrates:
+#   - the portable text generator (Zizek::Generators.text);
+#   - notes attached to the failing example (test_case.note);
+#   - shrinking to a minimal counterexample; and
+#   - replaying the portable reproduce blob.
+
+require "zizek"
+
+module RoundtripExample
+  # The shrunk failure blob is identical in Go, Python, and Ruby.
+  PORTABLE_ROUNDTRIP_FAILURE = "AAEAAAAEAQAAADAAAAA="
+
+  module_function
+
+  # Compresses text into [count, char] runs. Deliberate bug: the run in
+  # progress is never flushed when the input ends, so the final run of every
+  # non-empty input is lost.
+  def encode(text)
+    runs = []
+    count = 0
+    current = nil
+    text.each_char do |char|
+      if count.positive? && char == current
+        count += 1
+        next
+      end
+      runs << [count, current] if count.positive?
+      current = char
+      count = 1
+    end
+    runs
+  end
+
+  def decode(runs)
+    runs.map { |count, char| char * count }.join
+  end
+
+  def property(test_case)
+    text = test_case.draw(Zizek::Generators.text.max_size(12))
+    test_case.note("text #{text.inspect} encodes to #{encode(text).inspect}")
+    decoded = decode(encode(text))
+    return if decoded == text
+
+    raise "round trip lost data: #{text.inspect} became #{decoded.inspect}"
+  end
+
+  def find_and_replay_bug
+    found =
+      begin
+        Zizek.check(method(:property), examples: 200, seed: 1)
+        raise "the round-trip bug should be discovered"
+      rescue Zizek::Failure => failure
+        failure
+      end
+
+    # The blob is a portable description of the shrunk choices: replaying it
+    # runs exactly the recorded example, here or in any other Zizek package.
+    begin
+      Zizek.check(method(:property), reproduce: found.blob)
+    rescue Zizek::Failure
+      return found
+    end
+    raise "the shrunk round-trip failure must replay"
+  end
+end
+
+puts RoundtripExample.find_and_replay_bug if $PROGRAM_NAME == __FILE__

data/examples/stack.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Port of Hegel's passing stack state machine. It demonstrates a model whose
+# rules include an assumption: push_pop is rejected while the stack is empty,
+# without rejecting the whole generated example.
+
+require "zizek"
+
+module StackExample
+  class IntegerStack
+    def initialize
+      @stack = []
+    end
+
+    def push(test_case)
+      @stack << test_case.draw(Zizek::Generators.integers)
+    end
+
+    def pop(_test_case)
+      @stack.pop
+    end
+
+    def pop_push(test_case)
+      value = test_case.draw(Zizek::Generators.integers)
+      initial = @stack.dup
+      @stack << value
+      raise "pop did not return the pushed value" unless @stack.pop == value
+      raise "push then pop changed the stack" unless @stack == initial
+    end
+
+    def push_pop(test_case)
+      initial = @stack.dup
+      value = @stack.pop
+      test_case.assume(!value.nil?)
+      @stack << value
+      raise "pop then push changed the stack" unless @stack == initial
+    end
+
+    def rules
+      [
+        Zizek::Stateful::Rule.new("push", ->(machine, test_case) { machine.push(test_case) }),
+        Zizek::Stateful::Rule.new("pop", ->(machine, test_case) { machine.pop(test_case) }),
+        Zizek::Stateful::Rule.new("pop_push", ->(machine, test_case) { machine.pop_push(test_case) }),
+        Zizek::Stateful::Rule.new("push_pop", ->(machine, test_case) { machine.push_pop(test_case) })
+      ]
+    end
+
+    def invariants
+      []
+    end
+  end
+
+  module_function
+
+  def property(test_case)
+    Zizek::Stateful.run(IntegerStack.new, test_case)
+  end
+
+  def verify_stack_model
+    Zizek.check(method(:property), examples: 100, seed: 1)
+    true
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  StackExample.verify_stack_model
+  puts "stack model passed"
+end

data/examples/tour.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# A tour of Zizek's draw and configuration surface, one scenario per feature:
+#
+#   1. bounded integers with a custom shrink target;
+#   2. assumptions that reject examples instead of failing them;
+#   3. boolean and byte draws shrinking together;
+#   4. bounded IEEE-754 floats with portable shrinking; and
+#   5. rejection limits (Zizek::TooManyRejections).
+#
+# Every scenario is deterministic: it uses a fixed seed and prints the shrunk
+# failure it expects to find.
+
+require "zizek"
+
+module TourExample
+  module_function
+
+  # shrink_towards: failures shrink to the failing value closest to the
+  # requested target instead of the interval minimum.
+  def shrink_targets
+    property = lambda do |test_case|
+      value = test_case.draw(
+        Zizek::Generators.integers.min_value(-1000).max_value(1000).shrink_towards(500)
+      )
+      test_case.note("value #{value}")
+      raise "value #{value} exceeds the budget of 700" if value > 700
+    end
+
+    begin
+      Zizek.check(property, examples: 300, seed: 1)
+      raise "expected a failure above 700"
+    rescue Zizek::Failure => failure
+      failure
+    end
+  end
+
+  # assume: odd draws are rejected (not failed), so the shrunk counterexample
+  # is the smallest *even* value above the limit.
+  def even_numbers_only
+    property = lambda do |test_case|
+      value = test_case.integer(0, 100)
+      test_case.assume(value.even?)
+      test_case.note("even value #{value}")
+      raise "even value #{value} exceeds 50" if value > 50
+    end
+
+    begin
+      Zizek.check(property, examples: 300, seed: 1)
+      raise "expected an even failure above 50"
+    rescue Zizek::Failure => failure
+      failure
+    end
+  end
+
+  # Low-level boolean and bytes draws shrinking together: the boolean stays
+  # true because false passes, and the payload shrinks to the single smallest
+  # high byte.
+  def flags_and_bytes
+    property = lambda do |test_case|
+      compressed = test_case.boolean
+      payload = test_case.bytes(1, 4)
+      test_case.note("compressed=#{compressed} payload=#{payload.unpack1('H*')}")
+      next unless compressed
+
+      payload.each_byte do |value|
+        raise format("compressed payload contains high byte 0x%02x", value) if value >= 0x80
+      end
+    end
+
+    begin
+      Zizek.check(property, examples: 300, seed: 1)
+      raise "expected a high-byte failure"
+    rescue Zizek::Failure => failure
+      failure
+    end
+  end
+
+  # Float generation, replay, and shrink ordering use the compiled float
+  # choice. The smallest value outside [0, 1) is exactly 1.0.
+  def bounded_floats
+    property = lambda do |test_case|
+      value = test_case.draw(
+        Zizek::Generators.floats.min_value(0.0).max_value(10.0)
+      )
+      test_case.note("value #{value.inspect}")
+      raise "float #{value.inspect} is outside [0, 1)" if value >= 1.0
+    end
+
+    begin
+      Zizek.check(property, examples: 300, seed: 1)
+      raise "expected a float failure"
+    rescue Zizek::Failure => failure
+      failure
+    end
+  end
+
+  # max_rejections: a property whose assumptions reject every example stops
+  # with TooManyRejections instead of searching forever.
+  def rejection_limit
+    property = lambda do |test_case|
+      value = test_case.integer(0, 1000)
+      test_case.assume(value > 1000) # impossible: every example is rejected
+    end
+
+    begin
+      Zizek.check(property, examples: 10, max_rejections: 20, seed: 1)
+      raise "expected TooManyRejections"
+    rescue Zizek::TooManyRejections => rejected
+      rejected
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  puts "== 1. integers with a shrink target =="
+  puts TourExample.shrink_targets.message
+  puts "\n== 2. assumptions =="
+  puts TourExample.even_numbers_only.message
+  puts "\n== 3. booleans and bytes =="
+  puts TourExample.flags_and_bytes.message
+  puts "\n== 4. bounded floats =="
+  puts TourExample.bounded_floats.message
+  puts "\n== 5. rejection limits =="
+  puts TourExample.rejection_limit.message
+end

data/lib/zizek/database.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+
+module Zizek
+  # Where a counterexample goes after the run that found it.
+  #
+  # A database is a cache that never needs invalidating. It stores raw
+  # serialized choice streams — the bytes under a reproduce blob, not the blob
+  # — keyed by a property's name, so the next run replays yesterday's failure
+  # instead of hoping to rediscover it.
+  #
+  # Both digests are the project's compiled keyed-draw hash (ir/keys.zir), so a
+  # directory written by this gem is byte-for-byte the directory the Python and
+  # Go packages write.
+  module Database
+    # Where a database goes when a caller asks for one without saying where.
+    DEFAULT_PATH = ".zizek/examples"
+
+    # An entry's filename: sixteen lowercase hex digits and nothing else.
+    # Anything else in a key directory belongs to something other than the
+    # engine — .name, a .gitignore, an editor's swap file — and is ignored
+    # rather than replayed.
+    ENTRY_PATTERN = /\A[0-9a-f]{16}\z/.freeze
+
+    # The file naming a key directory, for a human reading a checkout. The
+    # engine writes it and never reads it.
+    NAME_FILE = ".name"
+
+    module_function
+
+    # The sixteen hex digits a name or a stream is stored under.
+    #
+    # FNV-1a 64 over the tagged encoding compiled from ir/keys.zir, which is the
+    # same hash a keyed draw uses and the reason a database directory is
+    # portable across languages.
+    def digest(value)
+      format("%016x", Zizek.key_hash(value.to_s.b))
+    end
+
+    # The order stored entries are replayed in: shortest first, then bytes.
+    # The same order the shrinker prefers, so the simplest stored
+    # counterexample is the first one a run pays for.
+    def shortlex(stream)
+      [stream.bytesize, stream]
+    end
+
+    # Turn what a caller passed for `database:` into a database or nil.
+    #
+    # nil and false disable it, true selects the default directory, ":memory:"
+    # an in-memory one, any other string or Pathname a directory, and anything
+    # else is assumed to implement fetch/save/delete itself.
+    def resolve(spec)
+      return nil if spec.nil? || spec == false
+      return Directory.new(DEFAULT_PATH) if spec == true
+      return Memory.new if spec == ":memory:"
+      return Directory.new(spec) if spec.is_a?(String) || spec.respond_to?(:to_path)
+
+      %i[fetch save delete].each do |method|
+        next if spec.respond_to?(method)
+
+        raise ArgumentError,
+              "database must be a path, \":memory:\", true, nil, or an object " \
+              "responding to fetch/save/delete; #{spec.inspect} does not respond to #{method}"
+      end
+      spec
+    end
+
+    # A database that forgets when the process exits.
+    #
+    # For a suite that wants replay within a run — or a test about the database
+    # itself — without leaving anything behind.
+    class Memory
+      def initialize
+        @entries = Hash.new { |store, key| store[key] = [] }
+      end
+
+      def inspect
+        "#<Zizek::Database::Memory>"
+      end
+
+      def fetch(key)
+        @entries.key?(key) ? @entries[key].dup : []
+      end
+
+      def save(key, value)
+        stream = value.b.freeze
+        @entries[key] << stream unless @entries[key].include?(stream)
+      end
+
+      def delete(key, value)
+        return unless @entries.key?(key)
+
+        @entries[key].delete(value.b)
+        @entries.delete(key) if @entries[key].empty?
+      end
+    end
+
+    # A directory of counterexamples, one subdirectory per property.
+    #
+    # The layout is shared with every other zizek package, so a directory
+    # checked into version control replays in any of them:
+    #
+    #   .zizek/examples/
+    #     9dc0c2b1f8a17c4e/          # the key's digest
+    #       .name                    # the property's name, for a human
+    #       3a6e0f5c9b2d1877         # a stored stream
+    #
+    # Every operation is best-effort: a database that cannot be read or written
+    # must not fail a test that would otherwise pass.
+    class Directory
+      attr_reader :path
+
+      def initialize(path = DEFAULT_PATH)
+        @path = path.to_s
+      end
+
+      def inspect
+        "#<Zizek::Database::Directory #{path.inspect}>"
+      end
+
+      def ==(other)
+        other.is_a?(Directory) && other.path == path
+      end
+      alias eql? ==
+
+      def hash
+        [Directory, path].hash
+      end
+
+      def key_path(key)
+        File.join(path, Database.__send__(:digest, key))
+      end
+
+      def value_path(key, value)
+        File.join(key_path(key), Database.__send__(:digest, value))
+      end
+
+      private :key_path, :value_path
+
+      def fetch(key)
+        directory = key_path(key)
+        names = begin
+          Dir.children(directory)
+        rescue SystemCallError
+          return []
+        end
+        names.select { |name| ENTRY_PATTERN.match?(name) }.map do |name|
+          begin
+            File.binread(File.join(directory, name))
+          rescue SystemCallError
+            # Deleted between the listing and the read: a concurrent run
+            # collected it, which is exactly what it is supposed to do.
+            nil
+          end
+        end.compact
+      end
+
+      def save(key, value)
+        directory = key_path(key)
+        FileUtils.mkdir_p(directory)
+        name_file = File.join(directory, NAME_FILE)
+        Database.__send__(:atomic_write, name_file, key.to_s.b) unless File.exist?(name_file)
+        entry = File.join(directory, Database.__send__(:digest, value))
+        Database.__send__(:atomic_write, entry, value.b) unless File.exist?(entry)
+      rescue SystemCallError
+        nil
+      end
+
+      def delete(key, value)
+        File.unlink(value_path(key, value))
+        # An emptied key directory takes its .name with it, so a database that
+        # collected everything leaves no husk behind — but only once the last
+        # entry is gone, or a directory that still holds counterexamples would
+        # lose the label that says whose they are.
+        begin
+          directory = key_path(key)
+          return if Dir.children(directory).any? { |name| ENTRY_PATTERN.match?(name) }
+
+          File.unlink(File.join(directory, NAME_FILE))
+          Dir.rmdir(directory)
+        rescue SystemCallError
+          nil
+        end
+      rescue SystemCallError
+        nil
+      end
+    end
+
+    # Write through a temporary file, so a reader never sees a partial entry.
+    def atomic_write(path, payload)
+      directory = File.dirname(path)
+      temporary = Tempfile.create(".zizek", directory, binmode: true)
+      begin
+        temporary.write(payload)
+        temporary.close
+        File.rename(temporary.path, path)
+      rescue SystemCallError
+        begin
+          File.unlink(temporary.path)
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+
+    private_class_method :digest, :shortlex, :resolve, :atomic_write
+    private_constant :ENTRY_PATTERN, :NAME_FILE
+  end
+end