regresso 0.1.0

data/lib/regresso/comparator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Regresso
+  # Compares two data sources and produces a {Regresso::Result}.
+  class Comparator
+    # Creates a comparator for two data sources.
+    #
+    # @param source_a [#fetch] first data source
+    # @param source_b [#fetch] second data source
+    # @param config [Regresso::Configuration] comparison config
+    def initialize(source_a:, source_b:, config: Configuration.new)
+      @source_a = source_a
+      @source_b = source_b
+      @config = config
+    end
+
+    # Compares two sources and returns the comparison result.
+    #
+    # @return [Regresso::Result]
+    def compare
+      data_a = fetch_data(@source_a)
+      data_b = fetch_data(@source_b)
+
+      differ = Differ.new(@config)
+      diffs = differ.diff(data_a, data_b)
+
+      Result.new(
+        source_a: @source_a,
+        source_b: @source_b,
+        diffs: diffs,
+        config: @config
+      )
+    end
+
+    private
+
+    def fetch_data(source)
+      unless source.respond_to?(:fetch)
+        raise ArgumentError, "source must respond to #fetch"
+      end
+
+      source.fetch
+    end
+  end
+end

data/lib/regresso/configuration.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Regresso
+  # Stores comparison settings used by {Regresso::Differ} and {Regresso::Comparator}.
+  class Configuration
+    # Default numeric tolerance applied when no path-specific override exists.
+    #
+    # @return [Float]
+    attr_accessor :default_tolerance
+
+    # Paths or patterns to ignore during comparison.
+    #
+    # @return [Array<String,Regexp>]
+    attr_accessor :ignore_paths
+
+    # Per-path tolerance overrides keyed by JSON path string.
+    #
+    # @return [Hash{String => Float}]
+    attr_accessor :tolerance_overrides
+
+    # Whether array order must match during comparison.
+    #
+    # @return [Boolean]
+    attr_accessor :array_order_sensitive
+
+    # Whether numeric strings should be coerced when comparing.
+    #
+    # @return [Boolean]
+    attr_accessor :type_coercion
+
+    def initialize
+      @default_tolerance = 0.0
+      @ignore_paths = []
+      @tolerance_overrides = {}
+      @array_order_sensitive = true
+      @type_coercion = true
+    end
+
+    # Returns tolerance for a given path.
+    #
+    # @param path [Regresso::JsonPath]
+    # @return [Float]
+    def tolerance_for(path)
+      @tolerance_overrides[path.to_s] || @default_tolerance
+    end
+
+    # Checks if a path should be ignored.
+    #
+    # @param path [Regresso::JsonPath]
+    # @return [Boolean]
+    def ignored?(path)
+      @ignore_paths.any? { |pattern| path_matches?(path, pattern) }
+    end
+
+    # Merges another configuration into a new configuration.
+    #
+    # @param other [Regresso::Configuration]
+    # @return [Regresso::Configuration]
+    def merge(other)
+      dup.tap do |config|
+        unless other.default_tolerance.nil?
+          config.default_tolerance = other.default_tolerance
+        end
+
+        config.ignore_paths += other.ignore_paths if other.ignore_paths
+        config.tolerance_overrides.merge!(other.tolerance_overrides) if other.tolerance_overrides
+
+        unless other.array_order_sensitive.nil?
+          config.array_order_sensitive = other.array_order_sensitive
+        end
+
+        unless other.type_coercion.nil?
+          config.type_coercion = other.type_coercion
+        end
+      end
+    end
+
+    private
+
+    def path_matches?(path, pattern)
+      case pattern
+      when Regexp
+        path.to_s.match?(pattern)
+      when String
+        path_string = path.to_s
+        path_string == pattern || path_string.end_with?(pattern)
+      else
+        false
+      end
+    end
+  end
+end

data/lib/regresso/differ.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Regresso
+  # Computes differences between two structured values.
+  class Differ
+    # @param config [Regresso::Configuration]
+    def initialize(config)
+      @config = config
+    end
+
+    # Computes differences between two values.
+    #
+    # @param a [Object]
+    # @param b [Object]
+    # @param path [Regresso::JsonPath]
+    # @return [Array<Regresso::Difference>]
+    def diff(a, b, path = JsonPath.root)
+      return [] if should_ignore?(path)
+
+      if a.is_a?(Hash) && b.is_a?(Hash)
+        diff_hashes(a, b, path)
+      elsif a.is_a?(Array) && b.is_a?(Array)
+        diff_arrays(a, b, path)
+      else
+        diff_values(a, b, path)
+      end
+    end
+
+    private
+
+    def diff_hashes(a, b, path)
+      (a.keys | b.keys).flat_map do |key|
+        next_path = path / key
+        if a.key?(key) && b.key?(key)
+          diff(a[key], b[key], next_path)
+        elsif a.key?(key)
+          [Difference.new(path: next_path, old_value: a[key], new_value: nil)]
+        else
+          [Difference.new(path: next_path, old_value: nil, new_value: b[key])]
+        end
+      end
+    end
+
+    def diff_arrays(a, b, path)
+      if @config.array_order_sensitive
+        max = [a.length, b.length].max
+        (0...max).flat_map do |index|
+          next_path = path / index
+          if index < a.length && index < b.length
+            diff(a[index], b[index], next_path)
+          elsif index < a.length
+            [Difference.new(path: next_path, old_value: a[index], new_value: nil)]
+          else
+            [Difference.new(path: next_path, old_value: nil, new_value: b[index])]
+          end
+        end
+      else
+        sorted_a = sort_by_canonical(a)
+        sorted_b = sort_by_canonical(b)
+        max = [sorted_a.length, sorted_b.length].max
+        (0...max).flat_map do |index|
+          next_path = path / index
+          if index < sorted_a.length && index < sorted_b.length
+            diff(sorted_a[index], sorted_b[index], next_path)
+          elsif index < sorted_a.length
+            [Difference.new(path: next_path, old_value: sorted_a[index], new_value: nil)]
+          else
+            [Difference.new(path: next_path, old_value: nil, new_value: sorted_b[index])]
+          end
+        end
+      end
+    end
+
+    def diff_values(a, b, path)
+      return [] if values_equal?(a, b, path)
+
+      [Difference.new(path: path, old_value: a, new_value: b)]
+    end
+
+    def values_equal?(a, b, path)
+      return true if a == b
+
+      if @config.type_coercion
+        coerced_a = numeric_value(a)
+        coerced_b = numeric_value(b)
+        return numeric_equal?(coerced_a, coerced_b, path) if coerced_a && coerced_b
+      end
+
+      if a.is_a?(Numeric) && b.is_a?(Numeric)
+        numeric_equal?(a, b, path)
+      end
+    end
+
+    def numeric_equal?(a, b, path)
+      tolerance = @config.tolerance_for(path)
+      (a.to_f - b.to_f).abs <= tolerance
+    end
+
+    def numeric_value(value)
+      return value.to_f if value.is_a?(Numeric)
+      return value.to_s.to_f if value.is_a?(String) && value.match?(/\A-?\d+(\.\d+)?\z/)
+
+      nil
+    end
+
+    def should_ignore?(path)
+      @config.ignored?(path)
+    end
+
+    def sort_by_canonical(array)
+      array.sort_by { |value| canonical_value(value) }
+    end
+
+    def canonical_value(value)
+      case value
+      when Hash
+        "{" + value.sort_by { |k, _| k.to_s }
+                        .map { |k, v| "#{k}:#{canonical_value(v)}" }
+                        .join(",") + "}"
+      when Array
+        "[" + value.map { |v| canonical_value(v) }.join(",") + "]"
+      else
+        value.inspect
+      end
+    end
+  end
+end

data/lib/regresso/difference.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Regresso
+  # Represents a single difference between two values.
+  class Difference
+    # @return [Regresso::JsonPath]
+    attr_reader :path
+
+    # @return [Object]
+    attr_reader :old_value
+
+    # @return [Object]
+    attr_reader :new_value
+
+    # @return [Symbol] one of :added, :removed, :changed
+    attr_reader :type
+
+    # @param path [Regresso::JsonPath]
+    # @param old_value [Object]
+    # @param new_value [Object]
+    def initialize(path:, old_value:, new_value:)
+      @path = path
+      @old_value = old_value
+      @new_value = new_value
+      @type = determine_type
+      freeze
+    end
+
+    # Returns a human-readable diff description.
+    #
+    # @return [String]
+    def to_s
+      "#{path}: #{old_value.inspect} -> #{new_value.inspect}"
+    end
+
+    private
+
+    def determine_type
+      return :added if old_value.nil?
+      return :removed if new_value.nil?
+
+      :changed
+    end
+  end
+end

data/lib/regresso/history/entry.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Regresso
+  # Persistent storage structures for historical comparisons.
+  module History
+    # A stored snapshot of a single comparison result.
+    class Entry
+      # @return [String]
+      attr_reader :id
+
+      # @return [Time]
+      attr_reader :timestamp
+
+      # @return [Hash]
+      attr_reader :result
+
+      # @return [Hash]
+      attr_reader :metadata
+
+      # @param id [String]
+      # @param timestamp [Time]
+      # @param result [Hash]
+      # @param metadata [Hash]
+      def initialize(id:, timestamp:, result:, metadata: {})
+        @id = id
+        @timestamp = timestamp
+        @result = result
+        @metadata = metadata
+      end
+
+      # @return [Boolean]
+      def passed?
+        value = result[:success]
+        value = result["success"] if value.nil?
+        !!value
+      end
+
+      # @return [Boolean]
+      def failed?
+        !passed?
+      end
+
+      # @return [Hash]
+      def to_h
+        {
+          "id" => id,
+          "timestamp" => timestamp.iso8601,
+          "result" => result,
+          "metadata" => metadata
+        }
+      end
+
+      # @param hash [Hash]
+      # @return [Regresso::History::Entry]
+      def self.from_h(hash)
+        source = hash.transform_keys(&:to_s)
+        result = source["result"] || {}
+        result = result.transform_keys(&:to_s) if result.respond_to?(:transform_keys)
+        metadata = source["metadata"] || {}
+        metadata = metadata.transform_keys(&:to_s) if metadata.respond_to?(:transform_keys)
+        new(
+          id: source["id"] || hash[:id],
+          timestamp: Time.parse(source["timestamp"] || hash[:timestamp].to_s),
+          result: result,
+          metadata: metadata
+        )
+      end
+    end
+  end
+end

data/lib/regresso/history/file_backend.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Regresso
+  module History
+    # File-backed persistence for {Regresso::History::Entry}.
+    class FileBackend
+      # @param storage_dir [String]
+      def initialize(storage_dir: "tmp/regresso_history")
+        @storage_dir = storage_dir
+        FileUtils.mkdir_p(@storage_dir)
+      end
+
+      # @param entry [Regresso::History::Entry]
+      # @return [void]
+      def save(entry)
+        File.write(path_for(entry.id), JSON.generate(entry.to_h))
+      end
+
+      # @param id [String]
+      # @return [Regresso::History::Entry,nil]
+      def find(id)
+        path = path_for(id)
+        return nil unless File.exist?(path)
+
+        Entry.from_h(JSON.parse(File.read(path)))
+      end
+
+      # @return [Array<Regresso::History::Entry>]
+      def all
+        Dir.glob(File.join(@storage_dir, "*.json")).map do |path|
+          Entry.from_h(JSON.parse(File.read(path)))
+        end.sort_by(&:timestamp).reverse
+      end
+
+      # @param id [String]
+      # @return [void]
+      def delete(id)
+        FileUtils.rm_f(path_for(id))
+      end
+
+      private
+
+      def path_for(id)
+        File.join(@storage_dir, "#{id}.json")
+      end
+    end
+  end
+end

data/lib/regresso/history/statistics.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Regresso
+  module History
+    # Computes aggregated statistics from stored entries.
+    class Statistics
+      # @param entries [Array<Regresso::History::Entry>]
+      def initialize(entries)
+        @entries = entries
+      end
+
+      # @return [Hash] summarized statistics
+      def calculate
+        {
+          total_runs: @entries.size,
+          success_rate: calculate_success_rate,
+          average_duration: calculate_average_duration,
+          failure_trend: calculate_failure_trend,
+          common_failures: identify_common_failures,
+          by_day: aggregate_by_day
+        }
+      end
+
+      private
+
+      def calculate_success_rate
+        return 0.0 if @entries.empty?
+
+        passed = @entries.count(&:passed?)
+        (passed.to_f / @entries.size * 100).round(2)
+      end
+
+      def calculate_average_duration
+        return 0.0 if @entries.empty?
+
+        total = @entries.sum { |entry| entry.result[:duration].to_f }
+        (total / @entries.size).round(2)
+      end
+
+      def calculate_failure_trend
+        @entries.group_by { |entry| entry.timestamp.to_date }
+                .transform_values { |list| list.count(&:failed?) }
+      end
+
+      def identify_common_failures
+        failures = @entries.select(&:failed?)
+        failures.group_by { |entry| entry.metadata["error"] || "unknown" }
+                .transform_values(&:size)
+                .sort_by { |_key, value| -value }
+                .to_h
+      end
+
+      def aggregate_by_day
+        @entries.group_by { |entry| entry.timestamp.to_date }
+                .transform_values do |list|
+          {
+            total: list.size,
+            passed: list.count(&:passed?),
+            failed: list.count(&:failed?)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/regresso/history/store.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Regresso
+  module History
+    # Manages persistence and queries for historical results.
+    class Store
+      # @param storage_backend [Regresso::History::FileBackend]
+      def initialize(storage_backend: FileBackend.new)
+        @backend = storage_backend
+      end
+
+      # @param result [Regresso::Parallel::ParallelResult]
+      # @param metadata [Hash]
+      # @return [Regresso::History::Entry]
+      def record(result, metadata = {})
+        entry = Entry.new(
+          id: SecureRandom.uuid,
+          timestamp: Time.now,
+          result: serialize_result(result),
+          metadata: metadata
+        )
+        @backend.save(entry)
+        entry
+      end
+
+      # @param id [String]
+      # @return [Regresso::History::Entry,nil]
+      def find(id)
+        @backend.find(id)
+      end
+
+      # @param filters [Hash]
+      # @return [Array<Regresso::History::Entry>]
+      def list(filters = {})
+        entries = @backend.all
+        filter_entries(entries, filters)
+      end
+
+      # @param start_date [Time,nil]
+      # @param end_date [Time,nil]
+      # @param status [Symbol,nil]
+      # @param limit [Integer,nil]
+      # @return [Array<Regresso::History::Entry>]
+      def query(start_date: nil, end_date: nil, status: nil, limit: nil)
+        entries = @backend.all
+        entries = entries.select do |entry|
+          within_range?(entry, start_date, end_date) && status_match?(entry, status)
+        end
+        limit ? entries.first(limit) : entries
+      end
+
+      # @param period [Symbol]
+      # @return [Hash]
+      def statistics(period: :week)
+        entries = list_for_period(period)
+        Statistics.new(entries).calculate
+      end
+
+      private
+
+      def serialize_result(result)
+        {
+          total: result.total,
+          passed: result.passed,
+          failed: result.failed,
+          errors: result.errors,
+          success: result.success?,
+          duration: result.total_duration
+        }
+      end
+
+      def filter_entries(entries, filters)
+        return entries if filters.empty?
+
+        entries.select do |entry|
+          matches = true
+          matches &&= status_match?(entry, filters[:status]) if filters[:status]
+          matches &&= within_range?(entry, filters[:start_date], filters[:end_date])
+          matches
+        end
+      end
+
+      def status_match?(entry, status)
+        return true unless status
+
+        case status
+        when :passed
+          entry.passed?
+        when :failed
+          entry.failed?
+        else
+          true
+        end
+      end
+
+      def within_range?(entry, start_date, end_date)
+        start_ok = start_date.nil? || entry.timestamp >= start_date
+        end_ok = end_date.nil? || entry.timestamp <= end_date
+        start_ok && end_ok
+      end
+
+      def list_for_period(period)
+        now = Time.now
+        start_date = case period
+                     when :day
+                       now - 60 * 60 * 24
+                     when :week
+                       now - 60 * 60 * 24 * 7
+                     when :month
+                       now - 60 * 60 * 24 * 30
+                     else
+                       now - 60 * 60 * 24 * 7
+                     end
+
+        query(start_date: start_date)
+      end
+    end
+  end
+end

data/lib/regresso/history/trend_reporter.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Regresso
+  module History
+    # Generates an HTML trend report for stored results.
+    class TrendReporter
+      # @param store [Regresso::History::Store]
+      def initialize(store)
+        @store = store
+      end
+
+      # @param period [Symbol]
+      # @return [String] HTML report
+      def generate(period: :week)
+        stats = @store.statistics(period: period)
+        template = <<~HTML
+          <!doctype html>
+          <html lang="en">
+            <head>
+              <meta charset="utf-8">
+              <title>Regresso Trends</title>
+              <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+              <style>
+                body { font-family: Arial, sans-serif; padding: 20px; }
+                .chart { max-width: 800px; margin: 32px auto; }
+              </style>
+            </head>
+            <body>
+              <h1>Regresso Trends</h1>
+              <p>Total runs: <%= stats[:total_runs] %></p>
+              <p>Success rate: <%= stats[:success_rate] %>%</p>
+
+              <div class="chart">
+                <canvas id="successChart"></canvas>
+              </div>
+
+              <script>
+                const data = <%= JSON.generate(stats[:by_day]) %>;
+                const labels = Object.keys(data);
+                const successRates = labels.map(day => {
+                  const dayData = data[day];
+                  return dayData.total === 0 ? 0 : (dayData.passed / dayData.total * 100).toFixed(2);
+                });
+
+                new Chart(document.getElementById('successChart'), {
+                  type: 'line',
+                  data: {
+                    labels: labels,
+                    datasets: [{
+                      label: 'Success Rate (%)',
+                      data: successRates,
+                      borderColor: '#1d4d9f',
+                      backgroundColor: 'rgba(29, 77, 159, 0.2)'
+                    }]
+                  }
+                });
+              </script>
+            </body>
+          </html>
+        HTML
+
+        ERB.new(template).result(binding)
+      end
+    end
+  end
+end

data/lib/regresso/history.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "history/entry"
+require_relative "history/file_backend"
+require_relative "history/statistics"
+require_relative "history/store"
+require_relative "history/trend_reporter"