regresso 0.1.0

data/lib/regresso/json_path.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Regresso
+  # Immutable JSON-path-like identifier used in diffs.
+  class JsonPath
+    # @return [Array<String,Integer>]
+    attr_reader :segments
+
+    # Returns the root path.
+    #
+    # @return [Regresso::JsonPath]
+    def self.root
+      new([])
+    end
+
+    # @param segments [Array<String,Integer>]
+    def initialize(segments)
+      @segments = segments.dup.freeze
+      freeze
+    end
+
+    # Returns a new path with the segment appended.
+    #
+    # @param segment [String,Integer]
+    # @return [Regresso::JsonPath]
+    def /(segment)
+      self.class.new(segments + [segment])
+    end
+
+    # Returns the string representation of the path.
+    #
+    # @return [String]
+    def to_s
+      return "$" if segments.empty?
+
+      segments.reduce("$") do |path, segment|
+        if segment.is_a?(Integer)
+          "#{path}[#{segment}]"
+        else
+          "#{path}.#{segment}"
+        end
+      end
+    end
+
+    # Compares paths by string representation.
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.respond_to?(:to_s)
+
+      to_s == other.to_s
+    end
+  end
+end

data/lib/regresso/minitest.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "regresso"
+require "regresso/snapshot_manager"
+
+# Minitest helpers for Regresso comparisons.
+# @!parse
+#   # Minitest namespace from the minitest gem.
+#   module ::Minitest
+#   end
+#
+#   # Base test class from minitest.
+#   class ::Minitest::Test
+#   end
+
+module Regresso
+  # Minitest integration helpers.
+  module Minitest
+    # Assertion helpers for regression testing.
+    module Assertions
+      # Asserts that two sources have no regression.
+      #
+      # @param source_a [Object]
+      # @param source_b [Object]
+      # @param tolerance [Float]
+      # @param ignore [Array<String,Regexp>]
+      # @param message [String,nil]
+      # @return [void]
+      def assert_no_regression(source_a, source_b, tolerance: 0.0, ignore: [], message: nil)
+        config = Regresso::Configuration.new
+        config.default_tolerance = tolerance
+        config.ignore_paths = ignore
+
+        comparator = Regresso::Comparator.new(
+          source_a: normalize_source(source_a),
+          source_b: normalize_source(source_b),
+          config: config
+        )
+
+        result = comparator.compare
+
+        msg = message || build_failure_message(result)
+        assert result.passed?, msg
+      end
+
+      # Asserts that an object matches a stored snapshot.
+      #
+      # @param actual [Object]
+      # @param snapshot_name [String]
+      # @param tolerance [Float]
+      # @param ignore [Array<String,Regexp>]
+      # @return [void]
+      def assert_matches_snapshot(actual, snapshot_name, tolerance: 0.0, ignore: [])
+        manager = Regresso::SnapshotManager.new
+        path = manager.path_for(snapshot_name)
+
+        if ENV["UPDATE_SNAPSHOTS"] || !File.exist?(path)
+          manager.save(snapshot_name, actual)
+          pass
+        else
+          expected = manager.load(snapshot_name)
+          assert_no_regression(expected, actual, tolerance: tolerance, ignore: ignore)
+        end
+      end
+
+      private
+
+      def normalize_source(source)
+        case source
+        when Regresso::Adapters::Base
+          source
+        when Hash
+          if source[:url] || source[:base_url]
+            base_url = source[:base_url] || source[:url]
+            Regresso::Adapters::Http.new(**source.merge(base_url: base_url).reject { |k, _| k == :url })
+          elsif source[:path] && source[:path].to_s.end_with?(".csv")
+            Regresso::Adapters::Csv.new(**source)
+          elsif source[:path]
+            Regresso::Adapters::JsonFile.new(**source)
+          else
+            Regresso::Adapters::Proc.new { source }
+          end
+        when String
+          if source.end_with?(".csv")
+            Regresso::Adapters::Csv.new(path: source)
+          else
+            Regresso::Adapters::JsonFile.new(path: source)
+          end
+        when ::Proc
+          Regresso::Adapters::Proc.new(source)
+        else
+          Regresso::Adapters::Proc.new { source }
+        end
+      end
+
+      def build_failure_message(result)
+        diffs = result.meaningful_diffs
+        "Expected no regression, found #{diffs.size} difference(s):\n" +
+          diffs.first(5).map { |diff| "  #{diff}" }.join("\n")
+      end
+    end
+  end
+end
+
+if defined?(::Minitest::Test)
+  ::Minitest::Test.include Regresso::Minitest::Assertions
+end

data/lib/regresso/notifiers/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Regresso
+  # Notification backends for reporting results.
+  module Notifiers
+    # Base class for notification integrations.
+    class Base
+      # Sends a notification if the notifier deems it necessary.
+      #
+      # @param result [Regresso::Parallel::ParallelResult]
+      # @return [void]
+      def notify(result)
+        return unless should_notify?(result)
+
+        send_notification(build_message(result))
+      end
+
+      private
+
+      def should_notify?(_result)
+        raise NotImplementedError, "Notifiers must implement #should_notify?"
+      end
+
+      def build_message(_result)
+        raise NotImplementedError, "Notifiers must implement #build_message"
+      end
+
+      def send_notification(_message)
+        raise NotImplementedError, "Notifiers must implement #send_notification"
+      end
+    end
+  end
+end

data/lib/regresso/notifiers/microsoft_teams.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+module Regresso
+  module Notifiers
+    # Microsoft Teams webhook notifier.
+    class MicrosoftTeams < Base
+      # @param webhook_url [String]
+      # @param notify_on [Symbol] :always, :failure, or :success
+      def initialize(webhook_url:, notify_on: :failure)
+        @webhook_url = webhook_url
+        @notify_on = notify_on
+      end
+
+      private
+
+      def should_notify?(result)
+        case @notify_on
+        when :always
+          true
+        when :failure
+          !result.success?
+        when :success
+          result.success?
+        else
+          false
+        end
+      end
+
+      def build_message(result)
+        {
+          "@type" => "MessageCard",
+          "@context" => "http://schema.org/extensions",
+          "summary" => "Regresso Report",
+          "themeColor" => result.success? ? "2ECC71" : "E74C3C",
+          "title" => "Regresso Report",
+          "sections" => [
+            {
+              "facts" => [
+                { "name" => "Total", "value" => result.total.to_s },
+                { "name" => "Passed", "value" => result.passed.to_s },
+                { "name" => "Failed", "value" => result.failed.to_s },
+                { "name" => "Errors", "value" => result.errors.to_s }
+              ]
+            }
+          ]
+        }
+      end
+
+      def send_notification(message)
+        Faraday.post(@webhook_url) do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(message)
+        end
+      end
+    end
+  end
+end

data/lib/regresso/notifiers/slack.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+module Regresso
+  module Notifiers
+    # Slack webhook notifier.
+    class Slack < Base
+      # @param webhook_url [String]
+      # @param channel [String,nil]
+      # @param notify_on [Symbol] :always, :failure, or :success
+      # @param mention [String,nil]
+      # @param username [String,nil]
+      # @param icon_emoji [String,nil]
+      def initialize(webhook_url:, channel: nil, notify_on: :failure, mention: nil, username: nil, icon_emoji: nil)
+        @webhook_url = webhook_url
+        @channel = channel
+        @notify_on = notify_on
+        @mention = mention
+        @username = username
+        @icon_emoji = icon_emoji
+      end
+
+      private
+
+      def should_notify?(result)
+        case @notify_on
+        when :always
+          true
+        when :failure
+          !result.success?
+        when :success
+          result.success?
+        else
+          false
+        end
+      end
+
+      def build_message(result)
+        status_text = result.success? ? "Tests passed" : "Regression detected"
+        text = [@mention, status_text].compact.join(" ")
+
+        message = {
+          channel: @channel,
+          username: @username,
+          icon_emoji: @icon_emoji,
+          text: text,
+          attachments: [
+            {
+              color: result.success? ? "good" : "danger",
+              fields: [
+                { title: "Total", value: result.total.to_s, short: true },
+                { title: "Failed", value: result.failed.to_s, short: true },
+                { title: "Errors", value: result.errors.to_s, short: true }
+              ]
+            }
+          ]
+        }
+
+        message.delete_if { |_key, value| value.nil? }
+      end
+
+      def send_notification(message)
+        Faraday.post(@webhook_url) do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(message)
+        end
+      end
+    end
+  end
+end

data/lib/regresso/notifiers.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "notifiers/base"
+require_relative "notifiers/slack"
+require_relative "notifiers/microsoft_teams"

data/lib/regresso/parallel/comparison_result.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Regresso
+  module Parallel
+    # Result wrapper for a single comparison execution.
+    class ComparisonResult
+      # @return [String]
+      attr_reader :name
+
+      # @return [Regresso::Result,nil]
+      attr_reader :result
+
+      # @return [StandardError,nil]
+      attr_reader :error
+
+      # @return [Float]
+      attr_reader :duration
+
+      # @param name [String]
+      # @param result [Regresso::Result,nil]
+      # @param error [StandardError,nil]
+      # @param duration [Float]
+      def initialize(name:, result: nil, error: nil, duration:)
+        @name = name
+        @result = result
+        @error = error
+        @duration = duration
+      end
+
+      def passed?
+        error.nil? && result&.passed?
+      end
+
+      def failed?
+        error.nil? && result&.failed?
+      end
+
+      def error?
+        !error.nil?
+      end
+
+      # @return [Symbol] :passed, :failed, or :error
+      def status
+        return :error if error?
+        return :passed if passed?
+
+        :failed
+      end
+    end
+  end
+end

data/lib/regresso/parallel/parallel_result.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Regresso
+  module Parallel
+    # Summary of multiple comparison results.
+    class ParallelResult
+      # @return [Integer]
+      attr_reader :total
+
+      # @return [Integer]
+      attr_reader :passed
+
+      # @return [Integer]
+      attr_reader :failed
+
+      # @return [Integer]
+      attr_reader :errors
+
+      # @return [Array<Regresso::Parallel::ComparisonResult>]
+      attr_reader :results
+
+      # @return [Float]
+      attr_reader :total_duration
+
+      # @param total [Integer]
+      # @param passed [Integer]
+      # @param failed [Integer]
+      # @param errors [Integer]
+      # @param results [Array<Regresso::Parallel::ComparisonResult>]
+      # @param total_duration [Float]
+      def initialize(total:, passed:, failed:, errors:, results:, total_duration:)
+        @total = total
+        @passed = passed
+        @failed = failed
+        @errors = errors
+        @results = results
+        @total_duration = total_duration
+      end
+
+      # @return [Boolean]
+      def success?
+        failed.zero? && errors.zero?
+      end
+
+      # @return [Hash]
+      def summary
+        {
+          total: total,
+          passed: passed,
+          failed: failed,
+          errors: errors,
+          success_rate: (passed.to_f / total * 100).round(2),
+          total_duration: total_duration.round(2)
+        }
+      end
+
+      # @return [Array<Regresso::Parallel::ComparisonResult>]
+      def failed_results
+        results.select(&:failed?)
+      end
+
+      # @return [Array<Regresso::Parallel::ComparisonResult>]
+      def error_results
+        results.select(&:error?)
+      end
+    end
+  end
+end

data/lib/regresso/parallel/result_aggregator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Regresso
+  module Parallel
+    # Aggregates comparison results into a summary.
+    class ResultAggregator
+      # @param results [Array<Regresso::Parallel::ComparisonResult>]
+      def initialize(results)
+        @results = results
+      end
+
+      # @return [Regresso::Parallel::ParallelResult]
+      def aggregate
+        ParallelResult.new(
+          total: @results.size,
+          passed: @results.count(&:passed?),
+          failed: @results.count(&:failed?),
+          errors: @results.count(&:error?),
+          results: @results,
+          total_duration: @results.sum(&:duration)
+        )
+      end
+    end
+  end
+end

data/lib/regresso/parallel/runner.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Regresso
+  # Parallel execution utilities for multiple comparisons.
+  module Parallel
+    # Executes multiple comparisons concurrently.
+    class Runner
+      # Default number of worker threads.
+      DEFAULT_WORKERS = 4
+
+      # @param comparisons [Array<Hash>]
+      # @param workers [Integer]
+      # @param config [Regresso::Configuration]
+      def initialize(comparisons:, workers: DEFAULT_WORKERS, config: Configuration.new)
+        @comparisons = comparisons
+        @workers = workers
+        @config = config
+      end
+
+      # @return [Regresso::Parallel::ParallelResult]
+      def run
+        results = execute_parallel
+        ResultAggregator.new(results).aggregate
+      end
+
+      private
+
+      def execute_parallel
+        queue = Queue.new
+        @comparisons.each { |comparison| queue << comparison }
+
+        threads = @workers.times.map do
+          Thread.new do
+            thread_results = []
+            loop do
+              comparison = queue.pop(true) rescue nil
+              break unless comparison
+
+              thread_results << execute_comparison(comparison)
+            end
+            thread_results
+          end
+        end
+
+        threads.flat_map(&:value)
+      end
+
+      def execute_comparison(comparison)
+        start_time = Time.now
+        comparator = Comparator.new(
+          source_a: comparison[:source_a],
+          source_b: comparison[:source_b],
+          config: @config
+        )
+        result = comparator.compare
+
+        ComparisonResult.new(
+          name: comparison[:name],
+          result: result,
+          duration: Time.now - start_time
+        )
+      rescue StandardError => e
+        ComparisonResult.new(
+          name: comparison[:name],
+          error: e,
+          duration: Time.now - start_time
+        )
+      end
+    end
+  end
+end

data/lib/regresso/parallel.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "parallel/comparison_result"
+require_relative "parallel/parallel_result"
+require_relative "parallel/result_aggregator"
+require_relative "parallel/runner"

data/lib/regresso/reporter.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "erb"
+
+module Regresso
+  # Formats a {Regresso::Result} into text, JSON, or HTML.
+  class Reporter
+    # @param result [Regresso::Result]
+    def initialize(result)
+      @result = result
+    end
+
+    # Generates a report string.
+    #
+    # @param format [Symbol]
+    # @return [String]
+    def generate(format)
+      case format
+      when :text
+        to_text
+      when :json
+        to_json
+      when :html
+        to_html
+      else
+        raise ArgumentError, "Unknown format: #{format}"
+      end
+    end
+
+    private
+
+    def to_text
+      lines = []
+      lines << "Regresso Report"
+      lines << "Passed: #{@result.passed?}"
+      lines << "Total diffs: #{@result.diffs.size}"
+      lines << "Meaningful diffs: #{@result.meaningful_diffs.size}"
+      lines << ""
+
+      @result.meaningful_diffs.each do |diff|
+        lines << "- #{diff}"
+      end
+
+      lines.join("\n")
+    end
+
+    def to_json
+      {
+        summary: @result.summary,
+        diffs: @result.diffs.map do |diff|
+          {
+            path: diff.path.to_s,
+            old_value: diff.old_value,
+            new_value: diff.new_value,
+            type: diff.type
+          }
+        end
+      }.to_json
+    end
+
+    def to_html
+      template_path = File.expand_path("templates/report.html.erb", __dir__)
+      template = File.read(template_path)
+      ERB.new(template).result(binding)
+    end
+  end
+end

data/lib/regresso/result.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Regresso
+  # Holds the outcome of comparing two sources.
+  class Result
+    # @return [Object]
+    attr_reader :source_a
+
+    # @return [Object]
+    attr_reader :source_b
+
+    # @return [Array<Regresso::Difference>]
+    attr_reader :diffs
+
+    # @return [Regresso::Configuration]
+    attr_reader :config
+
+    # @param source_a [Object]
+    # @param source_b [Object]
+    # @param diffs [Array<Regresso::Difference>]
+    # @param config [Regresso::Configuration]
+    def initialize(source_a:, source_b:, diffs:, config:)
+      @source_a = source_a
+      @source_b = source_b
+      @diffs = diffs
+      @config = config
+    end
+
+    # @return [Boolean]
+    def passed?
+      meaningful_diffs.empty?
+    end
+
+    # @return [Boolean]
+    def failed?
+      !passed?
+    end
+
+    # Returns diffs not ignored by configuration.
+    #
+    # @return [Array<Regresso::Difference>]
+    def meaningful_diffs
+      @meaningful_diffs ||= diffs.reject { |diff| config.ignored?(diff.path) }
+    end
+
+    # Returns a summary hash.
+    #
+    # @return [Hash]
+    def summary
+      {
+        total_diffs: diffs.size,
+        meaningful_diffs: meaningful_diffs.size,
+        ignored_diffs: diffs.size - meaningful_diffs.size,
+        passed: passed?
+      }
+    end
+
+    # Generates a report string for the given format.
+    #
+    # @param format [Symbol]
+    # @return [String]
+    def to_report(format: :text)
+      unless defined?(Regresso::Reporter)
+        raise NotImplementedError, "Reporter is not available"
+      end
+
+      Reporter.new(self).generate(format)
+    end
+  end
+end