verity 0.1.0

data/lib/verity/assertions.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require "pp"
+
+module Verity
+  # Public: Raised when an assertion fails. Distinct from unexpected exceptions
+  # so the runner can differentiate assertion failures from errors.
+  class AssertionError < StandardError; end
+
+  # Public: Raised when a test body runs longer than its `timeout:` (see DSL).
+  class TestTimeoutError < StandardError; end
+
+  # Public: Assertion methods mixed into the DSL. Every assertion has a
+  # corresponding `refute_*` negation. All accept an optional `message:`
+  # keyword that overrides the default failure text.
+  module Assertions
+    # Public: Assert that a value is truthy.
+    #
+    # check   - The value to test.
+    # message - Optional String or Proc failure message.
+    #
+    # Raises AssertionError if check is falsy.
+    def assert(check, message: nil)
+      return if check
+      fail_assertion(message) { "Expected truthy but got #{check.inspect}" }
+    end
+
+    # Public: Assert that a value is falsy.
+    #
+    # check   - The value to test.
+    # message - Optional String or Proc failure message.
+    #
+    # Raises AssertionError if check is truthy.
+    def refute(check, message: nil)
+      return unless check
+      fail_assertion(message) { "Expected falsy but got #{check.inspect}" }
+    end
+
+    # Public: Assert that a value is nil.
+    #
+    # actual  - The value to test.
+    # message - Optional String or Proc failure message.
+    #
+    # Raises AssertionError when actual is not nil.
+    def assert_nil(actual, message: nil)
+      return if actual.nil?
+      fail_assertion(message) { "Expected nil but got #{actual.inspect}" }
+    end
+
+    # Public: Assert that a value is not nil.
+    #
+    # actual  - The value to test.
+    # message - Optional String or Proc failure message.
+    #
+    # Raises AssertionError when actual is nil.
+    def refute_nil(actual, message: nil)
+      return unless actual.nil?
+      fail_assertion(message) { "Expected non-nil but got nil" }
+    end
+
+    # Public: Assert that two values are equal using `==`.
+    #
+    # actual   - The value produced by the code under test.
+    # expected - The reference value.
+    # message  - Optional String or Proc failure message.
+    #
+    # Raises AssertionError when actual != expected.
+    def assert_equal(actual:, expected:, message: nil)
+      return if actual == expected
+      fail_assertion(message) { "Expected values to be equal\n#{format_diff(actual, expected)}" }
+    end
+
+    # Public: Assert that two values are NOT equal using `==`.
+    #
+    # actual   - The value produced by the code under test.
+    # expected - The reference value that should differ.
+    # message  - Optional String or Proc failure message.
+    #
+    # Raises AssertionError when actual == expected.
+    def refute_equal(actual:, expected:, message: nil)
+      return unless actual == expected
+      fail_assertion(message) { "Expected values to differ, but both were #{actual.inspect}" }
+    end
+
+    # Public: Assert that two references point to the same object (identity
+    # via `equal?`).
+    #
+    # actual   - The object produced by the code under test.
+    # expected - The exact object expected.
+    # message  - Optional String or Proc failure message.
+    #
+    # Raises AssertionError when the objects are not identical.
+    def assert_same(actual:, expected:, message: nil)
+      return if actual.equal?(expected)
+      fail_assertion(message) do
+        "Expected same object\n" \
+          "  actual:   #{actual.inspect} (object_id: #{actual.object_id})\n" \
+          "  expected: #{expected.inspect} (object_id: #{expected.object_id})"
+      end
+    end
+
+    # Public: Assert that two references are NOT the same object.
+    #
+    # actual   - The object produced by the code under test.
+    # expected - The object that should be a different instance.
+    # message  - Optional String or Proc failure message.
+    #
+    # Raises AssertionError when the objects are identical.
+    def refute_same(actual:, expected:, message: nil)
+      return unless actual.equal?(expected)
+      fail_assertion(message) do
+        "Expected different objects, both were #{actual.inspect} (object_id: #{actual.object_id})"
+      end
+    end
+
+    # Public: Assert that the block raises one of the given exception classes.
+    # Optionally verify the error message matches a pattern.
+    #
+    # error_classes - One or more Exception subclasses expected.
+    # match         - String or Regexp matched against the error message (default nil).
+    # message       - Optional String or Proc failure message.
+    # block         - Block expected to raise.
+    #
+    # Examples
+    #
+    #   assert_raises(ArgumentError) { Integer("nope") }
+    #   # => #<ArgumentError: ...>
+    #
+    # Returns the caught exception on success.
+    # Raises ArgumentError if no error classes are given.
+    # Raises AssertionError if the block does not raise as expected.
+    def assert_raises(*error_classes, match: nil, message: nil, &block)
+      raise ArgumentError, "assert_raises requires at least one error class" if error_classes.empty?
+
+      begin
+        block.call
+      rescue *error_classes => e
+        if match
+          satisfied = match.is_a?(Regexp) ? e.message =~ match : e.message.include?(match)
+          unless satisfied
+            fail_assertion(message) do
+              "#{e.class} raised but message #{e.message.inspect} did not match #{match.inspect}"
+            end
+          end
+        end
+        return e
+      rescue => e
+        fail_assertion(message) do
+          "Expected #{error_class_names(error_classes)} but #{e.class} was raised: #{e.message}"
+        end
+      end
+
+      fail_assertion(message) { "Expected #{error_class_names(error_classes)} but nothing was raised" }
+    end
+
+    # Public: Assert that the block does NOT raise the specified exceptions.
+    # When no error classes are given, asserts that nothing is raised at all.
+    # When a match pattern is provided, only matching messages trigger failure.
+    #
+    # error_classes - Zero or more Exception subclasses that must not be raised.
+    # match         - String or Regexp; only messages matching this cause failure (default nil).
+    # message       - Optional String or Proc failure message.
+    # block         - Block to execute.
+    #
+    # Raises AssertionError if the block raises a matching exception.
+    def refute_raises(*error_classes, match: nil, message: nil, &block)
+      if error_classes.empty?
+        begin
+          block.call
+        rescue => e
+          if match
+            satisfied = match.is_a?(Regexp) ? e.message =~ match : e.message.include?(match)
+            raise unless satisfied
+            fail_assertion(message) do
+              "Expected no exception with message matching #{match.inspect}, " \
+                "but #{e.class} was raised: #{e.message}"
+            end
+          else
+            fail_assertion(message) { "Expected no exception but #{e.class} was raised: #{e.message}" }
+          end
+        end
+      else
+        begin
+          block.call
+        rescue *error_classes => e
+          if match
+            satisfied = match.is_a?(Regexp) ? e.message =~ match : e.message.include?(match)
+            if satisfied
+              fail_assertion(message) do
+                "#{e.class} raised with message matching #{match.inspect}: #{e.message}"
+              end
+            end
+          else
+            fail_assertion(message) do
+              "Expected #{error_class_names(error_classes)} not to be raised, " \
+                "but #{e.class} was raised: #{e.message}"
+            end
+          end
+        end
+      end
+    end
+
+    # Public: Assert that a numeric value is within delta of the expected value.
+    # Internally adjusts for floating-point epsilon scaling.
+    #
+    # expected - Numeric reference value.
+    # actual   - Numeric value under test.
+    # delta    - Numeric maximum allowed difference.
+    # message  - Optional String or Proc failure message.
+    #
+    # Raises AssertionError when the difference exceeds delta.
+    def assert_in_delta(expected:, actual:, delta:, message: nil)
+      return if within_delta?(actual, expected, delta)
+      fail_assertion(message) do
+        "Expected #{actual.inspect} to be within #{delta} of #{expected.inspect}, " \
+          "difference was #{(actual - expected).abs}"
+      end
+    end
+
+    # Public: Assert that a numeric value is NOT within delta of the expected value.
+    #
+    # expected - Numeric reference value.
+    # actual   - Numeric value under test.
+    # delta    - Numeric maximum allowed difference.
+    # message  - Optional String or Proc failure message.
+    #
+    # Raises AssertionError when the difference is within delta.
+    def refute_in_delta(expected:, actual:, delta:, message: nil)
+      return unless within_delta?(actual, expected, delta)
+      fail_assertion(message) do
+        "Expected #{actual.inspect} to be outside #{delta} of #{expected.inspect}, " \
+          "but difference was #{(actual - expected).abs}"
+      end
+    end
+
+    # Public: Assert that a value matches a Regexp or includes a String.
+    #
+    # pattern - Regexp or String to match against.
+    # actual  - The value under test.
+    # message - Optional String or Proc failure message.
+    #
+    # Raises AssertionError when actual does not match pattern.
+    def assert_match(pattern:, actual:, message: nil)
+      return if match?(pattern, actual)
+      fail_assertion(message) { "Expected #{actual.inspect} to match #{pattern.inspect}" }
+    end
+
+    # Public: Assert that a value does NOT match a Regexp or include a String.
+    #
+    # pattern - Regexp or String to match against.
+    # actual  - The value under test.
+    # message - Optional String or Proc failure message.
+    #
+    # Raises AssertionError when actual matches pattern.
+    def refute_match(pattern:, actual:, message: nil)
+      return unless match?(pattern, actual)
+      fail_assertion(message) { "Expected #{actual.inspect} not to match #{pattern.inspect}" }
+    end
+
+    # Public: Assert that a collection includes the given item.
+    #
+    # item       - The element to look for.
+    # collection - An object responding to `include?`.
+    # message    - Optional String or Proc failure message.
+    #
+    # Raises AssertionError when item is not found.
+    def assert_includes(item:, collection:, message: nil)
+      return if collection.include?(item)
+      fail_assertion(message) { "Expected collection to include #{item.inspect}" }
+    end
+
+    # Public: Assert that a collection does NOT include the given item.
+    #
+    # item       - The element to look for.
+    # collection - An object responding to `include?`.
+    # message    - Optional String or Proc failure message.
+    #
+    # Raises AssertionError when item is found.
+    def refute_includes(item:, collection:, message: nil)
+      return unless collection.include?(item)
+      fail_assertion(message) { "Expected collection not to include #{item.inspect}" }
+    end
+
+    private
+
+    def fail_assertion(custom_message, &default_message)
+      msg = custom_message ? resolve_message(custom_message) : default_message.call
+      raise Verity::AssertionError, msg
+    end
+
+    def resolve_message(message)
+      message.is_a?(Proc) ? message.call : message
+    end
+
+    def within_delta?(actual, expected, delta)
+      # Scale epsilon by the magnitude of the operands to account for floating
+      # point representation error (e.g. (1.1 - 1.0).abs > 0.1 in IEEE 754).
+      tolerance = delta + Float::EPSILON * [actual.abs, expected.abs].max
+      (actual - expected).abs <= tolerance
+    end
+
+    def match?(pattern, actual)
+      pattern.is_a?(Regexp) ? actual =~ pattern : actual.include?(pattern)
+    end
+
+    def error_class_names(classes)
+      classes.map(&:name).join(", ")
+    end
+
+    def format_diff(actual, expected)
+      actual_str   = PP.pp(actual,   +"").chomp
+      expected_str = PP.pp(expected, +"").chomp
+      "  actual:   #{actual_str}\n  expected: #{expected_str}"
+    end
+  end
+end

data/lib/verity/configuration.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "etc"
+
+module Verity
+  # Public: Holds all user-configurable settings for a Verity test run.
+  # Access via `Verity.configuration` or inside a `Verity.configure` block.
+  #
+  # Examples
+  #
+  #   Verity.configure do |c|
+  #     c.test_globs    = ["test/**/*_test.rb"]
+  #     c.worker_count  = :cpus
+  #     c.reporter      = Verity::Reporters::DotsReporter.new($stdout)
+  #   end
+  class Configuration
+    # Public: String path for the SQLite manifest database. Use ":memory:" for
+    # an in-process database (single-worker only; cannot be used with parallel
+    # workers). Default: "verity/manifest.db" (relative to the process working
+    # directory, typically the project root).
+    #
+    # Public: Array of glob Strings matched against the working directory to
+    # discover test files. Default: ["verity/**/*_test.rb"].
+    #
+    # Public: Integer worker count, or :cpus / "cpus" to auto-detect from
+    # Etc.nprocessors. Default: 1.
+    #
+    # Public: Object implementing the Verity::Reporter interface that receives
+    # lifecycle callbacks. Default: ColoredDotsReporter writing to $stdout.
+    #
+    # Public: Test dispatch order for manifest runs: :random (default; shuffled
+    # once in the coordinator) or :fingerprint (sorted). A non-nil #shuffle_seed
+    # always implies a shuffle, even if test_order is :fingerprint.
+    #
+    # Public: Integer RNG seed for shuffled order. When nil and order is random,
+    # a seed is chosen, stored here, and printed to stderr (the number only)
+    # before workers start.
+    #
+    # Public: Optional Array of [absolute_path, Integer line] pairs (from CLI
+    # file:line). When non-empty, only tests whose #line matches, or that have
+    # an enclosing #group opened on that file:line, are runnable.
+    attr_accessor :manifest_path, :test_globs, :worker_count, :reporter,
+                  :test_order, :shuffle_seed, :location_filters
+
+    def initialize
+      set_defaults!
+    end
+
+    def set_defaults!
+      @manifest_path = "verity/manifest.db"
+      @test_globs = ["verity/**/*_test.rb"]
+      @worker_count = :cpus
+      @reporter = Verity::Reporters::ColoredDotsReporter.new($stdout)
+      @test_order = :random
+      @shuffle_seed = nil
+      @location_filters = []
+    end
+
+    # Public: Resolve worker_count to an Integer, expanding :cpus to the
+    # number of available processors.
+    #
+    # Returns a positive Integer.
+    # Raises ArgumentError if the value cannot be resolved or is less than 1.
+    def resolved_worker_count
+      n =
+        if self.class.cpus_worker_token?(worker_count)
+          [Etc.nprocessors, 1].max
+        else
+          begin
+            Integer(worker_count)
+          rescue TypeError, ArgumentError
+            raise ArgumentError,
+                  "worker_count must be a positive Integer or :cpus / \"cpus\" (got #{worker_count.inspect})"
+          end
+        end
+      raise ArgumentError, "worker_count must be >= 1 (got #{n})" if n < 1
+
+      n
+    end
+
+    # Public: Check whether the manifest is configured as in-memory.
+    #
+    # Returns true when manifest_path is ":memory:".
+    def memory_manifest?
+      manifest_path == ":memory:"
+    end
+
+    # Public: Expand test_globs into a sorted, deduplicated list of file paths.
+    #
+    # Returns a sorted Array of String file paths.
+    def test_files
+      test_globs.flat_map { |pattern| Dir.glob(pattern) }.uniq.sort
+    end
+
+    class << self
+      # Internal: Determine whether a value represents the :cpus worker token.
+      # Accepts :cpus, :cpu, "cpus", or "cpu" (case-insensitive).
+      #
+      # value - Symbol or String to check.
+      #
+      # Returns true if the value is a cpus token.
+      def cpus_worker_token?(value)
+        case value
+        when :cpus, :cpu
+          true
+        when String
+          s = value.strip.downcase
+          s == "cpus" || s == "cpu"
+        else
+          false
+        end
+      end
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/verity/fingerprint.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "digest"
+require "pathname"
+require "prism"
+
+module Verity
+  # Public: Content-addressed fingerprinting for test bodies. Parses source
+  # files with Prism to produce stable identifiers that survive line-number
+  # shifts when unrelated code changes, while disambiguating tests with
+  # identical bodies by appending the line number.
+  module Fingerprint
+    HEX_LENGTH = 16
+
+    class << self
+      THREAD_KEY = :__verity_fp_plan__
+
+      # Internal: Parse the given source file and install its line-to-fingerprint
+      # mapping on the current thread. Must be called before loading a test file.
+      #
+      # absolute_path - String absolute filesystem path to the source file.
+      #
+      # Returns the plan Hash (line => fingerprint).
+      def install_plan!(absolute_path)
+        Thread.current[THREAD_KEY] = plan_file(absolute_path)
+      end
+
+      # Internal: Remove the current thread's fingerprint plan. Called after
+      # a test file finishes loading.
+      #
+      # Returns nil.
+      def clear_plan!
+        Thread.current[THREAD_KEY] = nil
+      end
+
+      # Internal: Look up the fingerprint for a source line from the current
+      # thread's installed plan.
+      #
+      # line - Integer source line number.
+      #
+      # Returns a String fingerprint, or nil if no plan is active or the line
+      # has no entry.
+      def lookup(line)
+        Thread.current[THREAD_KEY]&.[](line)
+      end
+
+      # Public: Generate a location-based fingerprint when the Prism plan
+      # does not cover a given line (e.g. dynamically generated tests).
+      #
+      # file - String file path.
+      # line - Integer line number.
+      #
+      # Returns a String in the form "relative/path:hex".
+      def fallback_fingerprint(file, line)
+        rel = relative_source_path(file)
+        sha = Digest::SHA1.hexdigest("#{file}:#{line}")[0, HEX_LENGTH]
+        "#{rel}:#{sha}"
+      end
+
+      # Internal: Parse a source file and build a Hash mapping each `test`
+      # call's line number to a content-addressed fingerprint string.
+      # Duplicate body hashes within the same file are disambiguated by
+      # appending the line number.
+      #
+      # absolute_path - String absolute path to the Ruby source file.
+      #
+      # Returns a Hash { Integer => String }.
+      def plan_file(absolute_path)
+        source = File.read(absolute_path, encoding: "UTF-8")
+        result = Prism.parse(source, filepath: File.expand_path(absolute_path))
+        return {} unless result.success?
+
+        program = result.value
+        rows = []
+        each_load_time_test(program) do |call|
+          body = call.block.body
+          canon = canonical(body)
+          body_hex = Digest::SHA1.hexdigest(canon)[0, HEX_LENGTH]
+          rows << { line: call.location.start_line, body_hex: body_hex }
+        end
+
+        relative = relative_source_path(absolute_path)
+        by_hex = rows.group_by { _1[:body_hex] }
+        plan = {}
+        rows.each do |row|
+          line = row[:line]
+          body_hex = row[:body_hex]
+          plan[line] =
+            if by_hex[body_hex].length > 1
+              "#{relative}:#{body_hex}:#{line}"
+            else
+              "#{relative}:#{body_hex}"
+            end
+        end
+        plan
+      end
+
+      def derive_method_suffix(fingerprint)
+        parts = fingerprint.split(":")
+        hex =
+          if parts.size >= 3 && parts.last.match?(/\A\d+\z/)
+            parts[-2]
+          else
+            parts[-1]
+          end
+        raise ArgumentError, "invalid fingerprint (expected ...:#{HEX_LENGTH} hex chars): #{fingerprint}" unless /\A[a-f0-9]{#{HEX_LENGTH}}\z/.match?(hex)
+
+        hex
+      end
+
+      private
+
+      def relative_source_path(absolute_path)
+        abs = File.expand_path(absolute_path)
+        Pathname(abs).relative_path_from(Pathname(Dir.pwd)).to_s
+      rescue ArgumentError
+        File.basename(abs)
+      end
+
+      def each_load_time_test(node, inside_block = false, &block)
+        return unless node.is_a?(Prism::Node)
+
+        if node.is_a?(Prism::CallNode) && !inside_block && verity_test_call?(node)
+          block.call(node)
+        end
+
+        node.compact_child_nodes.each do |child|
+          deeper = inside_block
+          deeper = true if node.is_a?(Prism::CallNode) && child.is_a?(Prism::BlockNode)
+          each_load_time_test(child, deeper, &block)
+        end
+      end
+
+      def verity_test_call?(node)
+        node.is_a?(Prism::CallNode) && node.name == :test && node.receiver.nil? && node.block
+      end
+
+      def canonical(node)
+        return "" if node.nil?
+
+        if node.is_a?(Prism::StatementsNode)
+          return node.body.map { canonical(_1) }.join(";")
+        end
+
+        if node.is_a?(Prism::Node)
+          label = node.class.name.split("::").last
+          inner = node.compact_child_nodes.map { canonical(_1) }.join(" ")
+          return "(#{label} #{inner})"
+        end
+
+        raise ArgumentError, "unexpected node: #{node.class}"
+      end
+    end
+  end
+end