rspec-rewind 0.1.0 → 1.0.0

data/lib/rspec/rewind/flaky_reporter.rb

@@ -18,36 +18,38 @@ module RSpec
 
       class NullReporter
         def record(_event); end
+
+        def flush; end
+
+        def close; end
       end
 
       class JsonlReporter
+        attr_reader :path
+
         def initialize(path)
           @path = path
           @mutex = Mutex.new
         end
 
         def record(event)
-          payload = {
-            schema_version: event.schema_version,
-            status: event.status,
-            retry_reason: event.retry_reason,
-            example_id: event.example_id,
-            description: event.description,
-            location: event.location,
-            attempt: event.attempt,
-            retries: event.retries,
-            exception_class: event.exception_class,
-            exception_message: event.exception_message,
-            duration: event.duration,
-            sleep_seconds: event.sleep_seconds,
-            timestamp: event.timestamp
-          }
+          payload = event.respond_to?(:to_h) ? event.to_h : {}
 
           @mutex.synchronize do
             FileUtils.mkdir_p(File.dirname(@path))
-            File.open(@path, 'a') { |file| file.puts(JSON.generate(payload)) }
+            File.open(@path, 'a') do |file|
+              file.flock(File::LOCK_EX)
+              file.puts(JSON.generate(payload))
+              file.flush
+            ensure
+              file&.flock(File::LOCK_UN)
+            end
           end
         end
+
+        def flush; end
+
+        def close; end
       end
     end
   end

data/lib/rspec/rewind/flaky_transition.rb

@@ -8,15 +8,32 @@ module RSpec
         @notifier = notifier
       end
 
-      def perform(attempt:, retries:, duration:)
+      def perform(
+        attempt:,
+        retries:,
+        duration:,
+        exception:,
+        total_duration: nil,
+        attempt_durations: nil,
+        first_failure_duration: nil,
+        sleep_total: 0.0,
+        budget_decision: nil
+      )
         event = @event_builder.build(
           status: :flaky,
-          retry_reason: nil,
+          retry_reason: :exception,
           attempt: attempt,
           retries: retries,
           duration: duration,
+          total_duration: total_duration,
+          attempt_durations: attempt_durations,
+          first_failure_duration: first_failure_duration,
           sleep_seconds: 0.0,
-          exception: nil
+          scheduled_sleep_seconds: 0.0,
+          actual_sleep_seconds: 0.0,
+          sleep_total: sleep_total,
+          budget_decision: budget_decision,
+          exception: exception
         )
 
         @notifier.publish_flaky(event)

data/lib/rspec/rewind/matcher_validation.rb

@@ -5,14 +5,27 @@ module RSpec
     module MatcherValidation
       private
 
-      def normalize_matchers(values, field:)
+      def normalize_matchers(values, field:, strict_exception_matchers: false)
         matchers = Array(values).flatten.compact
-        matchers.each { |matcher| validate_matcher!(matcher, field: field) }
+        matchers.each do |matcher|
+          validate_matcher!(
+            matcher,
+            field: field,
+            strict_exception_matchers: strict_exception_matchers
+          )
+        end
         matchers
       end
 
-      def validate_matcher!(matcher, field:)
-        return if matcher.is_a?(Module) || matcher.is_a?(Regexp) || matcher.respond_to?(:call)
+      def validate_matcher!(matcher, field:, strict_exception_matchers:)
+        if matcher.is_a?(Module)
+          return unless strict_exception_matchers
+          return if matcher.is_a?(Class) && matcher <= Exception
+
+          raise ArgumentError,
+                "#{field} Module entries must be Exception classes when strict matcher validation is enabled"
+        end
+        return if matcher.is_a?(Regexp) || matcher.respond_to?(:call)
 
         raise ArgumentError, "#{field} entries must be Module, Regexp, or callable"
       end

data/lib/rspec/rewind/retry_budget.rb

@@ -1,7 +1,21 @@
 # frozen_string_literal: true
 
+require 'fileutils'
+
 module RSpec
   module Rewind
+    BudgetDecision = Struct.new(
+      :allowed,
+      :limit,
+      :used,
+      :remaining,
+      keyword_init: true
+    ) do
+      def allowed?
+        allowed
+      end
+    end
+
     class RetryBudget
       attr_reader :limit, :used
 
@@ -12,13 +26,17 @@ module RSpec
       end
 
       def consume!
-        return true if unlimited?
+        consume.allowed?
+      end
+
+      def consume
+        return decision(true) if unlimited?
 
         @mutex.synchronize do
-          return false if @used >= @limit
+          return decision(false) if @used >= @limit
 
           @used += 1
-          true
+          decision(true)
         end
       end
 
@@ -32,8 +50,21 @@ module RSpec
         @limit.nil?
       end
 
+      def reset!
+        @mutex.synchronize { @used = 0 }
+      end
+
       private
 
+      def decision(allowed)
+        BudgetDecision.new(
+          allowed: allowed,
+          limit: @limit,
+          used: @used,
+          remaining: remaining
+        )
+      end
+
       def normalize_limit(limit)
         return nil if limit.nil?
 
@@ -48,5 +79,97 @@ module RSpec
         parsed
       end
     end
+
+    class FileRetryBudget
+      attr_reader :limit, :path
+
+      def initialize(limit:, path:)
+        @limit = normalize_limit(limit)
+        @path = path
+      end
+
+      def consume!
+        consume.allowed?
+      end
+
+      def consume
+        with_locked_counter do |used, file|
+          return decision(false, used) if used >= @limit
+
+          used += 1
+          write_used(file, used)
+          decision(true, used)
+        end
+      end
+
+      def used
+        with_locked_counter { |current| current }
+      end
+
+      def remaining
+        [@limit - used, 0].max
+      end
+
+      def unlimited?
+        false
+      end
+
+      def reset!
+        with_lock { |file| write_used(file, 0) }
+      end
+
+      private
+
+      def with_locked_counter
+        with_lock do |file|
+          current = read_used(file)
+          yield current, file
+        end
+      end
+
+      def with_lock
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.open(@path, File::RDWR | File::CREAT, 0o644) do |file|
+          file.flock(File::LOCK_EX)
+          yield file
+        ensure
+          file&.flock(File::LOCK_UN)
+        end
+      end
+
+      def read_used(file)
+        file.rewind
+        text = file.read
+        Integer(text.empty? ? '0' : text)
+      end
+
+      def write_used(file, value)
+        file.rewind
+        file.truncate(0)
+        file.write(value.to_s)
+        file.flush
+      end
+
+      def decision(allowed, used)
+        BudgetDecision.new(
+          allowed: allowed,
+          limit: @limit,
+          used: used,
+          remaining: [@limit - used, 0].max
+        )
+      end
+
+      def normalize_limit(limit)
+        parsed = begin
+          Integer(limit)
+        rescue TypeError, ArgumentError
+          raise ArgumentError, 'file retry budget must be a non-negative integer'
+        end
+
+        raise ArgumentError, 'file retry budget must be >= 0' if parsed.negative?
+
+        parsed
+      end
+    end
   end
 end

data/lib/rspec/rewind/retry_count_resolver.rb

@@ -4,6 +4,7 @@ module RSpec
   module Rewind
     class RetryCountResolver
       ENV_RETRIES_KEY = 'RSPEC_REWIND_RETRIES'
+      ENV_DISABLE_KEY = 'RSPEC_REWIND_DISABLE'
 
       def initialize(configuration:, metadata:)
         @configuration = configuration
@@ -11,8 +12,11 @@ module RSpec
       end
 
       def resolve(explicit_retries:)
-        env_retries = ENV.fetch(ENV_RETRIES_KEY, nil)
-        return parse_non_negative_integer(env_retries, source: ENV_RETRIES_KEY) if env_retries
+        return 0 if normalize_retry_override(explicit_retries) == 0 # rubocop:disable Style/NumericPredicate
+        return 0 if env_disabled?
+
+        env_retries = env_retries_value
+        return capped(parse_non_negative_integer(env_retries, source: ENV_RETRIES_KEY)) if env_retries
 
         configured = first_non_nil(
           normalize_retry_override(explicit_retries),
@@ -20,7 +24,7 @@ module RSpec
           @configuration.default_retries
         )
 
-        parse_non_negative_integer(configured, source: 'retries')
+        capped(parse_non_negative_integer(configured, source: 'retries'))
       end
 
       private
@@ -46,6 +50,25 @@ module RSpec
         parsed
       end
 
+      def env_retries_value
+        value = ENV.fetch(ENV_RETRIES_KEY, nil)
+        return nil if value.nil? || value.to_s.empty?
+
+        value
+      end
+
+      def env_disabled?
+        value = ENV.fetch(ENV_DISABLE_KEY, nil)
+        %w[1 true yes on].include?(value.to_s.downcase)
+      end
+
+      def capped(value)
+        max_retries = @configuration.max_retries
+        return value if max_retries.nil? || value <= max_retries
+
+        raise ArgumentError, "retries must be <= #{max_retries}"
+      end
+
       def first_non_nil(*values)
         values.find { |value| !value.nil? }
       end

data/lib/rspec/rewind/retry_decision.rb

@@ -2,43 +2,132 @@
 
 module RSpec
   module Rewind
+    RetryDecisionResult = Struct.new(
+      :allowed,
+      :reason,
+      :matched_retry_on,
+      :matched_skip_retry_on,
+      :matcher_error,
+      keyword_init: true
+    ) do
+      def allowed?
+        allowed
+      end
+    end
+
+    RetryContext = Struct.new(
+      :attempt,
+      :retries,
+      :metadata,
+      :budget_remaining,
+      :failure_fingerprint,
+      :elapsed_time,
+      :sleep_total,
+      keyword_init: true
+    )
+
     class RetryDecision
-      def initialize(exception:, example:, retry_on:, skip_retry_on:, retry_if:)
+      def initialize(
+        exception:,
+        example:,
+        retry_on:,
+        skip_retry_on:,
+        retry_if:,
+        retry_on_default: :all,
+        context: nil,
+        strict_callable_arity: false
+      )
         @exception = exception
         @example = example
         @retry_on = normalize_matchers(retry_on)
         @skip_retry_on = normalize_matchers(skip_retry_on)
         @retry_if = retry_if
+        @retry_on_default = retry_on_default
+        @context = context
+        @strict_callable_arity = strict_callable_arity
       end
 
       def retry?
-        return false unless @exception
-        return false if matches_any?(@skip_retry_on)
+        decision.allowed?
+      end
+
+      def decision
+        return rejected(:no_exception) unless @exception
+
+        skip_match = find_match(@skip_retry_on)
+        if skip_match.matched?
+          return rejected(
+            :skip_retry_on_matched,
+            matched_skip_retry_on: skip_match.description,
+            matcher_error: skip_match.error
+          )
+        end
 
-        return false if @retry_on.any? && !matches_any?(@retry_on)
+        retry_match = nil
+        if @retry_on.any?
+          retry_match = find_match(@retry_on)
+          unless retry_match.matched?
+            return rejected(
+              :retry_on_not_matched,
+              matcher_error: retry_match.error
+            )
+          end
+        elsif !retry_on_default_allowed?
+          return rejected(:retry_on_default_rejected)
+        end
+
+        if @retry_if && !call_with_context(@retry_if)
+          return rejected(
+            :predicate_rejected,
+            matched_retry_on: retry_match&.description
+          )
+        end
 
-        return true unless @retry_if
+        allowed(matched_retry_on: retry_match&.description)
+      end
 
-        !!call_with_context(@retry_if)
+      MatchResult = Struct.new(:matched, :description, :error, keyword_init: true) do
+        def matched?
+          matched
+        end
       end
 
       private
 
-      def matches_any?(matchers)
-        matchers.any? { |matcher| match?(matcher) }
-      end
+      def find_match(matchers)
+        last_error = nil
 
-      def match?(matcher)
-        case matcher
-        when Module
-          @exception.is_a?(matcher)
-        when Regexp
-          matcher.match?(@exception.message.to_s)
-        else
-          matcher.respond_to?(:call) && !!call_with_context(matcher)
+        matchers.each do |matcher|
+          result = match(matcher)
+          return result if result.matched?
+
+          last_error ||= result.error
         end
-      rescue StandardError
-        false
+
+        MatchResult.new(matched: false, error: last_error)
+      end
+
+      def match(matcher)
+        matched =
+          case matcher
+          when Module
+            @exception.is_a?(matcher)
+          when Regexp
+            matcher.match?(@exception.message.to_s)
+          else
+            matcher.respond_to?(:call) && !call_with_context(matcher).nil?
+          end
+
+        MatchResult.new(matched: matched, description: matcher_description(matcher))
+      rescue StandardError => e
+        MatchResult.new(matched: false, description: matcher_description(matcher), error: "#{e.class}: #{e.message}")
+      end
+
+      def retry_on_default_allowed?
+        return @exception.is_a?(StandardError) if @retry_on_default == :standard_errors
+        return false if @retry_on_default == :none
+
+        true
       end
 
       def call_with_context(callable)
@@ -46,7 +135,11 @@ module RSpec
         return callable.call if arity.zero?
 
         required = arity.negative? ? (-arity - 1) : arity
-        args = [@exception, @example]
+        args = [@exception, @example, @context]
+        if @strict_callable_arity && arity.positive? && required > args.length
+          raise ArgumentError, "callable accepts #{required} required arguments; maximum supported is #{args.length}"
+        end
+
         args << nil while args.length < required
 
         if arity.positive?
@@ -65,6 +158,21 @@ module RSpec
       def normalize_matchers(values)
         Array(values).flatten.compact
       end
+
+      def allowed(**attributes)
+        RetryDecisionResult.new(allowed: true, reason: :allowed, **attributes)
+      end
+
+      def rejected(reason, **attributes)
+        RetryDecisionResult.new(allowed: false, reason: reason, **attributes)
+      end
+
+      def matcher_description(matcher)
+        return matcher.description if matcher.respond_to?(:description)
+        return matcher.name if matcher.respond_to?(:name) && matcher.name
+
+        matcher.inspect
+      end
     end
   end
 end

data/lib/rspec/rewind/retry_delay_resolver.rb

@@ -3,26 +3,60 @@
 module RSpec
   module Rewind
     class RetryDelayResolver
-      def initialize(configuration:, metadata:, example:)
+      def initialize(configuration:, metadata:, example:, warn: ->(_message) {})
         @configuration = configuration
         @metadata = metadata || {}
         @example = example
+        @warn = warn
+        @delay_conflict_warned = false
       end
 
-      def resolve(retry_number:, backoff:, wait:, exception:)
+      DelayContext = Struct.new(
+        :retry_number,
+        :resolved_retries,
+        :metadata,
+        :previous_sleep_seconds,
+        :failure_fingerprint,
+        keyword_init: true
+      )
+
+      def resolve(
+        retry_number:,
+        backoff:,
+        wait:,
+        exception:,
+        resolved_retries: nil,
+        previous_sleep_seconds: 0.0,
+        failure_fingerprint: nil
+      )
         explicit_wait = first_non_nil(wait, @metadata[:rewind_wait])
-        return normalize_delay(explicit_wait) if explicit_wait
+        warn_delay_conflict(wait: wait, backoff: backoff)
+        return normalize_delay(explicit_wait) unless explicit_wait.nil?
 
         strategy = first_non_nil(backoff, @metadata[:rewind_backoff], @configuration.backoff)
         return normalize_delay(strategy) if strategy.is_a?(Numeric)
 
-        return 0.0 unless strategy.respond_to?(:call)
+        unless strategy.respond_to?(:call)
+          raise ArgumentError,
+                'backoff must be a non-negative numeric value or callable'
+        end
 
-        raw = strategy.call(
+        args = {
           retry_number: retry_number,
           example: @example,
           exception: exception
-        )
+        }
+        if accepts_keyword?(strategy, :context)
+          args[:context] = DelayContext.new(
+            retry_number: retry_number,
+            resolved_retries: resolved_retries,
+            metadata: @metadata,
+            previous_sleep_seconds: previous_sleep_seconds,
+            failure_fingerprint: failure_fingerprint
+          )
+        end
+
+        raw = strategy.call(**args)
 
         normalize_delay(raw)
       end
@@ -44,6 +78,23 @@ module RSpec
       def first_non_nil(*values)
         values.find { |value| !value.nil? }
       end
+
+      def warn_delay_conflict(wait:, backoff:)
+        return unless @configuration.warn_on_delay_conflict
+        return if @delay_conflict_warned
+        return unless !first_non_nil(wait, @metadata[:rewind_wait]).nil? &&
+                      !first_non_nil(backoff, @metadata[:rewind_backoff]).nil?
+
+        @delay_conflict_warned = true
+        @warn.call('[rspec-rewind] wait and backoff are both configured; wait takes precedence')
+      end
+
+      def accepts_keyword?(callable, keyword)
+        parameters = callable.respond_to?(:parameters) ? callable.parameters : callable.method(:call).parameters
+        parameters.any? do |type, name|
+          type == :keyrest || (%i[key keyreq].include?(type) && name == keyword)
+        end
+      end
     end
   end
 end