serialbench 0.1.0

data/lib/serialbench/cli.rb

@@ -0,0 +1,438 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'json'
+require 'yaml'
+require 'fileutils'
+
+module Serialbench
+  # Thor-based command line interface for SerialBench
+  class Cli < Thor
+    include Thor::Actions
+
+    desc 'benchmark', 'Run serialization benchmarks'
+    long_desc <<~DESC
+      Run the complete benchmark suite for all available serialization libraries.
+
+      This command will test parsing, generation, streaming, and memory usage
+      across XML, JSON, and TOML formats using all available libraries.
+    DESC
+    option :formats, type: :array, default: %w[xml json toml],
+                     desc: 'Formats to benchmark (xml, json, toml)'
+    option :output_format, type: :string, default: 'all',
+                           desc: 'Output format: all, json, yaml, html'
+    option :parsing_only, type: :boolean, default: false,
+                          desc: 'Run only parsing benchmarks'
+    option :generation_only, type: :boolean, default: false,
+                             desc: 'Run only generation benchmarks'
+    option :streaming_only, type: :boolean, default: false,
+                            desc: 'Run only streaming benchmarks'
+    option :memory_only, type: :boolean, default: false,
+                         desc: 'Run only memory usage benchmarks'
+    option :iterations, type: :numeric, default: 10,
+                        desc: 'Number of benchmark iterations'
+    option :warmup, type: :numeric, default: 3,
+                    desc: 'Number of warmup iterations'
+    def benchmark
+      say 'SerialBench - Comprehensive Serialization Performance Tests', :green
+      say '=' * 70, :green
+
+      # Validate formats
+      valid_formats = %w[xml json toml]
+      invalid_formats = options[:formats] - valid_formats
+      unless invalid_formats.empty?
+        say "Invalid formats: #{invalid_formats.join(', ')}", :red
+        say "Valid formats: #{valid_formats.join(', ')}", :yellow
+        exit 1
+      end
+
+      # Convert format strings to symbols
+      formats = options[:formats].map(&:to_sym)
+
+      # Show available serializers
+      show_available_serializers(formats)
+
+      # Run benchmarks
+      runner_options = {
+        formats: formats,
+        iterations: options[:iterations],
+        warmup: options[:warmup]
+      }
+
+      runner = Serialbench::BenchmarkRunner.new(**runner_options)
+
+      begin
+        results = run_selected_benchmarks(runner)
+        save_results(results)
+        show_summary(results) unless %w[json yaml].include?(options[:output_format])
+      rescue StandardError => e
+        say "Error running benchmarks: #{e.message}", :red
+        say e.backtrace.first(5).join("\n"), :red if ENV['DEBUG']
+        exit 1
+      end
+    end
+
+    desc 'list', 'List available serializers'
+    long_desc <<~DESC
+      Display all available serialization libraries grouped by format.
+
+      Shows which libraries are installed and available for benchmarking,
+      along with their versions.
+    DESC
+    option :format, type: :string, desc: 'Show only serializers for specific format'
+    def list
+      say 'Available Serializers', :green
+      say '=' * 30, :green
+
+      if options[:format]
+        format_sym = options[:format].to_sym
+        serializers = Serialbench::Serializers.available_for_format(format_sym)
+
+        if serializers.empty?
+          say "No available serializers for format: #{options[:format]}", :yellow
+        else
+          show_serializers_for_format(format_sym, serializers)
+        end
+      else
+        %i[xml json toml].each do |format|
+          serializers = Serialbench::Serializers.available_for_format(format)
+          next if serializers.empty?
+
+          show_serializers_for_format(format, serializers)
+          say ''
+        end
+      end
+    end
+
+    desc 'version', 'Show SerialBench version'
+    def version
+      say "SerialBench version #{Serialbench::VERSION}", :green
+    end
+
+    desc 'merge_results INPUT_DIRS... OUTPUT_DIR', 'Merge benchmark results from multiple runs'
+    long_desc <<~DESC
+      Merge benchmark results from multiple Ruby versions or different environments.
+
+      INPUT_DIRS should contain results.json files from different benchmark runs.
+      OUTPUT_DIR will contain the merged results and comparative reports.
+
+      Example:
+        serialbench merge_results ruby-3.0/results ruby-3.1/results ruby-3.2/results merged_output/
+    DESC
+    def merge_results(*args)
+      if args.length < 2
+        say 'Error: Need at least one input directory and one output directory', :red
+        say 'Usage: serialbench merge_results INPUT_DIRS... OUTPUT_DIR', :yellow
+        exit 1
+      end
+
+      output_dir = args.pop
+      input_dirs = args
+
+      say "Merging benchmark results from #{input_dirs.length} directories to #{output_dir}", :green
+
+      begin
+        merger = Serialbench::ResultMerger.new
+        merged_file = merger.merge_directories(input_dirs, output_dir)
+        say "Results merged successfully to: #{merged_file}", :green
+      rescue StandardError => e
+        say "Error merging results: #{e.message}", :red
+        exit 1
+      end
+    end
+
+    desc 'github_pages INPUT_DIRS... OUTPUT_DIR', 'Generate GitHub Pages HTML from multiple benchmark runs'
+    long_desc <<~DESC
+      Merge benchmark results from multiple Ruby versions and generate a GitHub Pages compatible HTML report.
+
+      INPUT_DIRS should contain results.json files from different benchmark runs.
+      OUTPUT_DIR will contain index.html and styles.css ready for GitHub Pages deployment.
+
+      This command combines merge_results and HTML generation in one step.
+
+      Example:
+        serialbench github_pages ruby-3.0/results ruby-3.1/results ruby-3.2/results docs/
+    DESC
+    def github_pages(*args)
+      if args.length < 2
+        say 'Error: Need at least one input directory and one output directory', :red
+        say 'Usage: serialbench github_pages INPUT_DIRS... OUTPUT_DIR', :yellow
+        exit 1
+      end
+
+      output_dir = args.pop
+      input_dirs = args
+
+      say "Generating GitHub Pages from #{input_dirs.length} benchmark directories", :green
+
+      begin
+        merger = Serialbench::ResultMerger.new
+
+        # Merge results
+        say 'Step 1: Merging benchmark results...', :yellow
+        merger.merge_directories(input_dirs, output_dir)
+
+        # Generate GitHub Pages HTML
+        say 'Step 2: Generating GitHub Pages HTML...', :yellow
+        files = merger.generate_github_pages_html(output_dir)
+
+        say 'GitHub Pages generated successfully!', :green
+        say 'Files created:', :cyan
+        say "  HTML: #{files[:html]}", :white
+        say "  CSS: #{files[:css]}", :white
+        say '', :white
+        say 'To deploy to GitHub Pages:', :cyan
+        say '1. Commit and push the generated files to your repository', :white
+        say '2. Enable GitHub Pages in repository settings', :white
+        say '3. Set source to the branch containing these files', :white
+      rescue StandardError => e
+        say "Error generating GitHub Pages: #{e.message}", :red
+        exit 1
+      end
+    end
+
+    desc 'generate_reports DATA_FILE', 'Generate reports from benchmark data'
+    long_desc <<~DESC
+      Generate HTML and AsciiDoc reports from existing benchmark data.
+
+      DATA_FILE should be a JSON file containing benchmark results.
+    DESC
+    def generate_reports(data_file)
+      say "Generating reports from data in #{data_file}", :green
+
+      unless File.exist?(data_file)
+        say "Data file does not exist: #{data_file}", :red
+        exit 1
+      end
+
+      begin
+        Serialbench.generate_reports_from_data(data_file)
+        say 'Reports generated successfully!', :green
+      rescue StandardError => e
+        say "Error generating reports: #{e.message}", :red
+        exit 1
+      end
+    end
+
+    private
+
+    def show_available_serializers(formats)
+      say "\nAvailable serializers:", :cyan
+
+      formats.each do |format|
+        serializers = Serialbench::Serializers.available_for_format(format)
+        next if serializers.empty?
+
+        serializer_names = serializers.map do |serializer_class|
+          serializer = serializer_class.new
+          "#{serializer.name} v#{serializer.version}"
+        end
+
+        say "  #{format.upcase}: #{serializer_names.join(', ')}", :white
+      end
+
+      say "\nTest data sizes: small, medium, large", :cyan
+      say ''
+    end
+
+    def show_serializers_for_format(format, serializers)
+      say "#{format.upcase}:", :cyan
+
+      serializers.each do |serializer_class|
+        serializer = serializer_class.new
+        features = []
+        features << 'streaming' if serializer.supports_streaming?
+        features << 'built-in' if %w[json rexml].include?(serializer.name)
+
+        feature_text = features.empty? ? '' : " (#{features.join(', ')})"
+        say "  ✓ #{serializer.name} v#{serializer.version}#{feature_text}", :green
+      end
+    end
+
+    def run_selected_benchmarks(runner)
+      results = { environment: runner.environment_info }
+
+      if options[:parsing_only]
+        say 'Running parsing benchmarks...', :yellow
+        results[:parsing] = runner.run_parsing_benchmarks
+      elsif options[:generation_only]
+        say 'Running generation benchmarks...', :yellow
+        results[:generation] = runner.run_generation_benchmarks
+      elsif options[:streaming_only]
+        say 'Running streaming benchmarks...', :yellow
+        results[:streaming] = runner.run_streaming_benchmarks
+      elsif options[:memory_only]
+        say 'Running memory benchmarks...', :yellow
+        results[:memory_usage] = runner.run_memory_benchmarks
+      else
+        say 'Running all benchmarks...', :yellow
+        results = runner.run_all_benchmarks
+      end
+
+      results
+    end
+
+    def save_results(results)
+      case options[:output_format]
+      when 'json'
+        save_json_results(results)
+      when 'yaml'
+        save_yaml_results(results)
+      when 'html'
+        generate_html_reports(results)
+      else
+        # Generate all formats
+        save_json_results(results)
+        save_yaml_results(results)
+        generate_html_reports(results)
+      end
+
+      show_generated_files
+    end
+
+    def save_json_results(results)
+      FileUtils.mkdir_p('results/data')
+
+      # Add Ruby version to results
+      results[:ruby_version] = RUBY_VERSION
+      results[:ruby_platform] = RUBY_PLATFORM
+      results[:timestamp] = Time.now.iso8601
+
+      File.write('results/data/results.json', JSON.pretty_generate(results))
+      say 'JSON results saved to: results/data/results.json', :green
+    end
+
+    def save_yaml_results(results)
+      FileUtils.mkdir_p('results/data')
+
+      # Add Ruby version to results
+      results[:ruby_version] = RUBY_VERSION
+      results[:ruby_platform] = RUBY_PLATFORM
+      results[:timestamp] = Time.now.iso8601
+
+      File.write('results/data/results.yaml', results.to_yaml)
+      say 'YAML results saved to: results/data/results.yaml', :green
+    end
+
+    def generate_html_reports(results)
+      say 'Generating reports...', :yellow
+      report_files = Serialbench.generate_reports(results)
+
+      say 'Reports generated:', :green
+      say "  HTML: #{report_files[:html]}", :white
+      say "  CSS: #{report_files[:css]}", :white
+    end
+
+    def show_generated_files
+      case options[:output_format]
+      when 'json'
+        say 'Files generated:', :cyan
+        say '  JSON: results/data/results.json', :white
+      when 'yaml'
+        say 'Files generated:', :cyan
+        say '  YAML: results/data/results.yaml', :white
+      when 'html'
+        say 'Files generated:', :cyan
+        say '  HTML: results/reports/benchmark_report.html', :white
+        say '  Charts: results/charts/*.svg', :white
+      else
+        say 'Files generated:', :cyan
+        say '  JSON: results/data/results.json', :white
+        say '  YAML: results/data/results.yaml', :white
+        say '  HTML: results/reports/benchmark_report.html', :white
+        say '  Charts: results/charts/*.svg', :white
+      end
+    end
+
+    def show_summary(results)
+      return unless results[:parsing] || results[:generation]
+
+      say "\n" + '=' * 50, :green
+      say 'BENCHMARK SUMMARY', :green
+      say '=' * 50, :green
+
+      show_parsing_summary(results[:parsing]) if results[:parsing]
+
+      show_generation_summary(results[:generation]) if results[:generation]
+
+      return unless results[:memory_usage]
+
+      show_memory_summary(results[:memory_usage])
+    end
+
+    def show_parsing_summary(parsing_results)
+      say "\nParsing Performance (operations/second):", :cyan
+
+      %i[small medium large].each do |size|
+        next unless parsing_results[size]
+
+        say "\n  #{size.capitalize} files:", :yellow
+
+        # Flatten the nested structure and sort by performance
+        flattened_results = []
+        parsing_results[size].each do |format, serializers|
+          serializers.each do |serializer_name, data|
+            flattened_results << ["#{format}/#{serializer_name}", data]
+          end
+        end
+
+        sorted_results = flattened_results.sort_by { |_, data| -data[:iterations_per_second] }
+
+        sorted_results.each do |serializer_name, data|
+          ops_per_sec = data[:iterations_per_second].round(2)
+          say "    #{serializer_name}: #{ops_per_sec} ops/sec", :white
+        end
+      end
+    end
+
+    def show_generation_summary(generation_results)
+      say "\nGeneration Performance (operations/second):", :cyan
+
+      %i[small medium large].each do |size|
+        next unless generation_results[size]
+
+        say "\n  #{size.capitalize} files:", :yellow
+
+        # Flatten the nested structure and sort by performance
+        flattened_results = []
+        generation_results[size].each do |format, serializers|
+          serializers.each do |serializer_name, data|
+            flattened_results << ["#{format}/#{serializer_name}", data]
+          end
+        end
+
+        sorted_results = flattened_results.sort_by { |_, data| -data[:iterations_per_second] }
+
+        sorted_results.each do |serializer_name, data|
+          ops_per_sec = data[:iterations_per_second].round(2)
+          say "    #{serializer_name}: #{ops_per_sec} ops/sec", :white
+        end
+      end
+    end
+
+    def show_memory_summary(memory_results)
+      say "\nMemory Usage (MB):", :cyan
+
+      %i[small medium large].each do |size|
+        next unless memory_results[size]
+
+        say "\n  #{size.capitalize} files:", :yellow
+
+        # Flatten the nested structure and sort by memory usage (ascending)
+        flattened_results = []
+        memory_results[size].each do |format, serializers|
+          serializers.each do |serializer_name, data|
+            flattened_results << ["#{format}/#{serializer_name}", data]
+          end
+        end
+
+        sorted_results = flattened_results.sort_by { |_, data| data[:allocated_memory] }
+
+        sorted_results.each do |serializer_name, data|
+          memory_mb = (data[:allocated_memory] / 1024.0 / 1024.0).round(2)
+          say "    #{serializer_name}: #{memory_mb} MB", :white
+        end
+      end
+    end
+  end
+end

data/lib/serialbench/memory_profiler.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Serialbench
+  class MemoryProfiler
+    def self.profile(&block)
+      return yield unless defined?(::MemoryProfiler)
+
+      ::MemoryProfiler.report(&block)
+    end
+
+    def self.available?
+      require 'memory_profiler'
+      defined?(::MemoryProfiler) ? true : false
+    rescue LoadError
+      false
+    end
+
+    def self.format_report(report)
+      return 'Memory profiling not available' unless report
+
+      {
+        total_allocated: report.total_allocated,
+        total_retained: report.total_retained,
+        allocated_memory: report.total_allocated_memsize,
+        retained_memory: report.total_retained_memsize,
+        allocated_objects_by_gem: report.allocated_memory_by_gem,
+        retained_objects_by_gem: report.retained_memory_by_gem
+      }
+    end
+  end
+end

data/lib/serialbench/result_formatter.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'csv'
+
+module Serialbench
+  class ResultFormatter
+    def initialize(results)
+      @results = results
+    end
+
+    def to_json(pretty: true)
+      if pretty
+        JSON.pretty_generate(@results)
+      else
+        JSON.generate(@results)
+      end
+    end
+
+    def to_csv
+      return '' unless @results && @results[:dom_parsing]
+
+      csv_data = []
+
+      # Header
+      csv_data << ['Category', 'File Size', 'Parser', 'Time (ms)', 'Iterations/sec', 'Memory (MB)', 'Error']
+
+      # DOM parsing results
+      add_category_to_csv(csv_data, 'DOM Parsing', @results[:dom_parsing])
+
+      # SAX parsing results
+      add_category_to_csv(csv_data, 'SAX Parsing', @results[:sax_parsing])
+
+      # XML generation results
+      add_category_to_csv(csv_data, 'XML Generation', @results[:xml_generation])
+
+      CSV.generate do |csv|
+        csv_data.each { |row| csv << row }
+      end
+    end
+
+    def save_to_files(output_dir = 'results/data')
+      FileUtils.mkdir_p(output_dir)
+
+      # Save JSON
+      json_file = File.join(output_dir, 'results.json')
+      File.write(json_file, to_json)
+
+      # Save CSV
+      csv_file = File.join(output_dir, 'results.csv')
+      File.write(csv_file, to_csv)
+
+      {
+        json: json_file,
+        csv: csv_file
+      }
+    end
+
+    def summary
+      return 'No results available' unless @results
+
+      summary_lines = []
+      summary_lines << 'XML Benchmarks Summary'
+      summary_lines << '=' * 50
+
+      if @results[:environment]
+        summary_lines << "Environment: Ruby #{@results[:environment][:ruby_version]} on #{@results[:environment][:ruby_platform]}"
+        summary_lines << "Timestamp: #{@results[:environment][:timestamp]}"
+        summary_lines << ''
+      end
+
+      # DOM parsing summary
+      if @results[:dom_parsing] && !@results[:dom_parsing].empty?
+        summary_lines << 'DOM Parsing Performance:'
+        add_category_summary(summary_lines, @results[:dom_parsing])
+        summary_lines << ''
+      end
+
+      # SAX parsing summary
+      if @results[:sax_parsing] && !@results[:sax_parsing].empty?
+        summary_lines << 'SAX Parsing Performance:'
+        add_category_summary(summary_lines, @results[:sax_parsing])
+        summary_lines << ''
+      end
+
+      # XML generation summary
+      if @results[:xml_generation] && !@results[:xml_generation].empty?
+        summary_lines << 'XML Generation Performance:'
+        add_category_summary(summary_lines, @results[:xml_generation])
+        summary_lines << ''
+      end
+
+      # Memory usage summary
+      if @results[:memory_usage] && !@results[:memory_usage].empty?
+        summary_lines << 'Memory Usage:'
+        add_memory_summary(summary_lines, @results[:memory_usage])
+      end
+
+      summary_lines.join("\n")
+    end
+
+    private
+
+    def add_category_to_csv(csv_data, category, results)
+      return unless results
+
+      results.each do |size, parsers|
+        parsers.each do |parser, data|
+          memory_mb = if @results[:memory_usage] && @results[:memory_usage][size] && @results[:memory_usage][size][parser]
+                        (@results[:memory_usage][size][parser][:allocated_memory] / 1024.0 / 1024.0).round(2)
+                      else
+                        nil
+                      end
+
+          csv_data << [
+            category,
+            size.to_s.capitalize,
+            parser.capitalize,
+            data[:error] ? nil : (data[:time_per_iteration] * 1000).round(2),
+            data[:error] ? nil : data[:iterations_per_second].round(2),
+            memory_mb,
+            data[:error] || nil
+          ]
+        end
+      end
+    end
+
+    def add_category_summary(summary_lines, results)
+      results.each do |size, parsers|
+        summary_lines << "  #{size.to_s.capitalize} files:"
+
+        # Sort parsers by performance (fastest first)
+        sorted_parsers = parsers.reject { |_, data| data[:error] }
+                                .sort_by { |_, data| data[:time_per_iteration] }
+
+        sorted_parsers.each_with_index do |(parser, data), index|
+          time_ms = (data[:time_per_iteration] * 1000).round(2)
+          rank = case index
+                 when 0 then '🥇'
+                 when 1 then '🥈'
+                 when 2 then '🥉'
+                 else '  '
+                 end
+          summary_lines << "    #{rank} #{parser.capitalize}: #{time_ms}ms"
+        end
+
+        # Show errors if any
+        errors = parsers.select { |_, data| data[:error] }
+        errors.each do |parser, data|
+          summary_lines << "    ❌ #{parser.capitalize}: #{data[:error]}"
+        end
+      end
+    end
+
+    def add_memory_summary(summary_lines, results)
+      results.each do |size, parsers|
+        summary_lines << "  #{size.to_s.capitalize} files:"
+
+        # Sort parsers by memory usage (lowest first)
+        sorted_parsers = parsers.reject { |_, data| data[:error] }
+                                .sort_by { |_, data| data[:allocated_memory] }
+
+        sorted_parsers.each_with_index do |(parser, data), index|
+          memory_mb = (data[:allocated_memory] / 1024.0 / 1024.0).round(2)
+          rank = case index
+                 when 0 then '🥇'
+                 when 1 then '🥈'
+                 when 2 then '🥉'
+                 else '  '
+                 end
+          summary_lines << "    #{rank} #{parser.capitalize}: #{memory_mb}MB"
+        end
+
+        # Show errors if any
+        errors = parsers.select { |_, data| data[:error] }
+        errors.each do |parser, data|
+          summary_lines << "    ❌ #{parser.capitalize}: #{data[:error]}"
+        end
+      end
+    end
+  end
+end