i18n-tasks 1.1.2 → 1.2.0

data/Rakefile

@@ -2,7 +2,11 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
-RSpec::Core::RakeTask.new(:rspec)
+RSpec::Core::RakeTask.new(:rspec) do |task|
+  if ENV["RSPEC_JUNIT_OUTPUT"]
+    task.rspec_opts = ["--format", "RspecJunitFormatter", "--out", ENV.fetch("RSPEC_JUNIT_OUTPUT")]
+  end
+end
 task default: :rspec
 
 task :irb do

data/benchmarks/bench_helper.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+require "bundler/setup"
+require "fileutils"
+
+begin
+  require "benchmark/ips"
+  require "memory_profiler"
+rescue LoadError => e
+  warn "#{e.message}\n\nBenchmark gems are missing. Install them with:\n\n  bundle install\n\n" \
+       "If you have BUNDLE_WITHOUT set, make sure it does not exclude the :bench group.\n"
+  exit 1
+end
+
+# Load the gem under test
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "i18n/tasks"
+
+require_relative "fixtures/generator"
+
+BENCH_ROOT = File.expand_path("..", __dir__)
+
+module BenchHelper
+  # Generate all fixture scales (idempotent - reads from cache unless forced).
+  def self.prepare_fixtures(force: false)
+    BenchmarkFixtures.generate_all(force: force)
+  end
+
+  # Build a configured I18n::Tasks::BaseTask context pointed at a fixture directory
+  # and yield it within the correct working directory.
+  #
+  # i18n-tasks resolves relative search paths against the current working directory
+  # at scan time, so the task must be used within Dir.chdir(fixture_dir).
+  #
+  # @param scale [:small, :medium, :large]
+  # @yieldparam task [I18n::Tasks::BaseTask]
+  def self.build_context(scale)
+    dir = BenchmarkFixtures.generate(scale)
+    config_file = File.join(dir, "config", "i18n-tasks.yml")
+    Dir.chdir(dir) do
+      yield I18n::Tasks::BaseTask.new(config_file: config_file)
+    end
+  end
+
+  # Run a block with working directory set to the fixture dir.
+  # The context is created fresh each time so memoized caches don't carry over.
+  def self.in_fixture_dir(scale)
+    dir = BenchmarkFixtures.generate(scale)
+    Dir.chdir(dir) { yield }
+  end
+
+  # Pre-warm the context so file-system caches are hot before timing.
+  def self.warm_context(context)
+    context.used_tree
+    context
+  rescue => e
+    warn "BenchHelper.warm_context failed: #{e.class}: #{e.message}"
+    context
+  end
+
+  # Print a section header.
+  def self.header(title)
+    puts
+    puts "=" * 60
+    puts "  #{title}"
+    puts "=" * 60
+    puts
+  end
+
+  # Save IPS results to a JSON file for baseline comparison.
+  #
+  # @param suite [Benchmark::IPS::Suite] the completed suite
+  # @param label [String] top-level key in the JSON object
+  # @param path [String] path to the results JSON file
+  def self.save_results(suite, label, path: File.join(BENCH_ROOT, "benchmarks", "results", "baseline.json"))
+    require "json"
+    FileUtils.mkdir_p(File.dirname(path))
+    existing = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+    existing["_env"] = environment_info
+    existing[label] ||= {}
+    suite.entries.each do |entry|
+      existing[label][entry.label] = {
+        ips: entry.stats.central_tendency.round(2),
+        ips_sd: entry.stats.error.round(2),
+        microseconds: (1_000_000.0 / entry.stats.central_tendency).round(2)
+      }
+    end
+    File.write(path, JSON.pretty_generate(existing))
+    puts "Results saved to #{path}"
+  end
+
+  # Compare an IPS suite against a stored baseline and warn about regressions.
+  #
+  # @param suite [Benchmark::IPS::Suite]
+  # @param label [String]
+  # @param threshold [Float] fraction below baseline that counts as a regression (default 0.10 = 10%)
+  # @param path [String] path to the baseline JSON file
+  # @return [Boolean] true if no regressions found
+  def self.compare_baseline(suite, label, threshold: 0.10,
+    path: File.join(BENCH_ROOT, "benchmarks", "results", "baseline.json"))
+    require "json"
+    return true unless File.exist?(path)
+
+    baseline = JSON.parse(File.read(path))
+
+    if (saved_env = baseline["_env"])
+      current_env = environment_info
+      mismatches = current_env.filter_map do |key, val|
+        "#{key}: baseline=#{saved_env[key].inspect} current=#{val.inspect}" if saved_env[key] != val
+      end
+      if mismatches.any?
+        warn "WARNING: baseline environment differs from current — comparison may be unreliable:\n" \
+             "  #{mismatches.join("\n  ")}"
+      end
+    end
+
+    section = baseline[label]
+    return true unless section
+
+    regressions = []
+    suite.entries.each do |entry|
+      baseline_entry = section[entry.label]
+      next unless baseline_entry
+
+      baseline_ips = baseline_entry["ips"].to_f
+      next if baseline_ips.zero?
+
+      current_ips = entry.stats.central_tendency
+      ratio = current_ips / baseline_ips
+      if ratio < (1 - threshold)
+        regressions << format("  %-55s  %.1fx slower  (%.0f vs %.0f ips)",
+          entry.label, 1.0 / ratio, current_ips, baseline_ips)
+      end
+    end
+
+    if regressions.any?
+      puts
+      puts "WARNING: REGRESSIONS DETECTED (>#{(threshold * 100).to_i}% slowdown):"
+      regressions.each { |r| puts r }
+      puts
+      false
+    else
+      true
+    end
+  end
+
+  # Returns a hash of relevant environment metadata for baseline comparison.
+  def self.environment_info
+    {
+      "ruby_version" => RUBY_VERSION,
+      "ruby_platform" => RUBY_PLATFORM,
+      "ruby_engine" => RUBY_ENGINE
+    }
+  end
+end

data/benchmarks/data_bench.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+# Benchmarks for YAML data loading and writing (the I/O layer).
+#
+# Measures the cost of:
+# - Parsing YAML locale files into Ruby hashes
+# - Dumping Ruby hashes back to YAML strings
+# - Building Siblings trees from parsed YAML hashes
+# - The full data[locale] load path used by BaseTask
+#
+# Usage:
+#   bundle exec ruby benchmarks/data_bench.rb
+#   bundle exec ruby benchmarks/data_bench.rb --save
+#   bundle exec ruby benchmarks/data_bench.rb --compare
+#   bundle exec ruby benchmarks/data_bench.rb --memory  # include memory profiles
+
+require_relative "bench_helper"
+
+require "yaml"
+require "i18n/tasks/data/adapter/yaml_adapter"
+require "i18n/tasks/data/tree/siblings"
+
+SAVE_RESULTS = ARGV.include?("--save")
+COMPARE_RESULTS = ARGV.include?("--compare")
+MEMORY_PROFILE = ARGV.include?("--memory")
+
+Siblings = I18n::Tasks::Data::Tree::Siblings
+YamlAdapter = I18n::Tasks::Data::Adapter::YamlAdapter
+
+# Build YAML strings of various sizes in memory (no disk I/O during benchmarks)
+def yaml_string_for_scale(scale)
+  dir = BenchmarkFixtures.generate(scale)
+  File.read(File.join(dir, "config", "locales", "en.yml"))
+end
+
+SMALL_YAML = yaml_string_for_scale(:small).freeze
+MEDIUM_YAML = yaml_string_for_scale(:medium).freeze
+LARGE_YAML = yaml_string_for_scale(:large).freeze
+
+SMALL_HASH = YamlAdapter.parse(SMALL_YAML, nil).freeze
+MEDIUM_HASH = YamlAdapter.parse(MEDIUM_YAML, nil).freeze
+LARGE_HASH = YamlAdapter.parse(LARGE_YAML, nil).freeze
+
+SMALL_TREE = Siblings.from_nested_hash(SMALL_HASH).freeze
+MEDIUM_TREE = Siblings.from_nested_hash(MEDIUM_HASH).freeze
+
+# ---------------------------------------------------------------------------
+# YAML parse benchmarks
+# ---------------------------------------------------------------------------
+
+BenchHelper.header("YAML parse (string → hash)")
+
+parse_suite = Benchmark.ips do |x|
+  x.config(warmup: 3, time: 10)
+
+  x.report("YAML parse small  (~#{SMALL_YAML.size / 1024}KB)") do
+    YamlAdapter.parse(SMALL_YAML, nil)
+  end
+
+  x.report("YAML parse medium (~#{MEDIUM_YAML.size / 1024}KB)") do
+    YamlAdapter.parse(MEDIUM_YAML, nil)
+  end
+
+  x.report("YAML parse large  (~#{LARGE_YAML.size / 1024}KB)") do
+    YamlAdapter.parse(LARGE_YAML, nil)
+  end
+
+  x.compare!
+end
+
+# ---------------------------------------------------------------------------
+# YAML dump benchmarks
+# ---------------------------------------------------------------------------
+
+BenchHelper.header("YAML dump (hash → string)")
+
+dump_suite = Benchmark.ips do |x|
+  x.config(warmup: 3, time: 10)
+
+  x.report("YAML dump small  tree") do
+    YamlAdapter.dump(SMALL_HASH, nil)
+  end
+
+  x.report("YAML dump medium tree") do
+    YamlAdapter.dump(MEDIUM_HASH, nil)
+  end
+
+  x.report("YAML dump large  tree") do
+    YamlAdapter.dump(LARGE_HASH, nil)
+  end
+
+  x.compare!
+end
+
+# ---------------------------------------------------------------------------
+# Hash → Siblings tree construction
+# ---------------------------------------------------------------------------
+
+BenchHelper.header("Hash → Siblings tree construction")
+
+load_suite = Benchmark.ips do |x|
+  x.config(warmup: 3, time: 10)
+
+  x.report("from_nested_hash small") do
+    Siblings.from_nested_hash(SMALL_HASH)
+  end
+
+  x.report("from_nested_hash medium") do
+    Siblings.from_nested_hash(MEDIUM_HASH)
+  end
+
+  x.report("from_nested_hash large") do
+    Siblings.from_nested_hash(LARGE_HASH)
+  end
+
+  x.compare!
+end
+
+# ---------------------------------------------------------------------------
+# Full data load via BaseTask
+# ---------------------------------------------------------------------------
+
+BenchHelper.header("Full data[locale] load via BaseTask")
+
+data_load_suite = Benchmark.ips do |x|
+  x.config(warmup: 2, time: 10)
+
+  [:small, :medium].each do |scale|
+    dir = BenchmarkFixtures.generate(scale)
+
+    x.report("data['en'] load (#{scale})") do
+      Dir.chdir(dir) do
+        task = I18n::Tasks::BaseTask.new(config_file: File.join(dir, "config", "i18n-tasks.yml"))
+        task.data["en"]
+      end
+    end
+  end
+
+  x.compare!
+end
+
+# ---------------------------------------------------------------------------
+# Memory profiles (opt-in via --memory)
+# ---------------------------------------------------------------------------
+
+if MEMORY_PROFILE
+  BenchHelper.header("Memory — YAML parse + tree build (medium)")
+  MemoryProfiler.report do
+    hash = YamlAdapter.parse(MEDIUM_YAML, nil)
+    Siblings.from_nested_hash(hash)
+  end.pretty_print(scale_bytes: true, detailed_report: false)
+
+  BenchHelper.header("Memory — YAML dump (medium)")
+  MemoryProfiler.report { YamlAdapter.dump(MEDIUM_HASH, nil) }
+    .pretty_print(scale_bytes: true, detailed_report: false)
+end
+
+passed = true
+if SAVE_RESULTS
+  BenchHelper.save_results(parse_suite, "data/yaml_parse")
+  BenchHelper.save_results(dump_suite, "data/yaml_dump")
+  BenchHelper.save_results(load_suite, "data/tree_load")
+  BenchHelper.save_results(data_load_suite, "data/full_load")
+end
+
+if COMPARE_RESULTS
+  passed = false unless BenchHelper.compare_baseline(parse_suite, "data/yaml_parse")
+  passed = false unless BenchHelper.compare_baseline(dump_suite, "data/yaml_dump")
+  passed = false unless BenchHelper.compare_baseline(load_suite, "data/tree_load")
+  passed = false unless BenchHelper.compare_baseline(data_load_suite, "data/full_load")
+end
+
+exit(1) if COMPARE_RESULTS && !passed

data/benchmarks/end_to_end_bench.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# End-to-end benchmarks for the full i18n-tasks pipeline.
+#
+# These measure the complete workflows that users actually run:
+#   - missing_keys: find translations present in base locale but missing elsewhere
+#   - unused_keys:  find keys defined in locale files but not used in source
+#   - used_tree:    scan all source files and build the usage tree
+#
+# These are the most important benchmarks for catching regressions — any change
+# to the scanner, data layer, or tree operations will show up here.
+#
+# Usage:
+#   bundle exec ruby benchmarks/end_to_end_bench.rb
+#   bundle exec ruby benchmarks/end_to_end_bench.rb --save    # save as new baseline
+#   bundle exec ruby benchmarks/end_to_end_bench.rb --compare # compare against baseline
+#   bundle exec ruby benchmarks/end_to_end_bench.rb --memory  # include memory profiles
+
+require_relative "bench_helper"
+
+SAVE_RESULTS = ARGV.include?("--save")
+COMPARE_RESULTS = ARGV.include?("--compare")
+MEMORY_PROFILE = ARGV.include?("--memory")
+
+all_suites = []
+
+# ---------------------------------------------------------------------------
+# Benchmark each pipeline operation across all scales
+# ---------------------------------------------------------------------------
+
+[:small, :medium, :large].each do |scale|
+  dir = BenchmarkFixtures.generate(scale)
+
+  BenchHelper.header("End-to-end pipeline — #{scale} fixture")
+
+  suite = Benchmark.ips do |x|
+    x.config(warmup: 2, time: 15)
+
+    x.report("used_tree     (#{scale})") do
+      Dir.chdir(dir) do
+        task = I18n::Tasks::BaseTask.new(config_file: File.join(dir, "config", "i18n-tasks.yml"))
+        task.used_tree
+      end
+    end
+
+    x.report("missing_keys  (#{scale})") do
+      Dir.chdir(dir) do
+        task = I18n::Tasks::BaseTask.new(config_file: File.join(dir, "config", "i18n-tasks.yml"))
+        task.missing_keys
+      end
+    end
+
+    x.report("unused_keys   (#{scale})") do
+      Dir.chdir(dir) do
+        task = I18n::Tasks::BaseTask.new(config_file: File.join(dir, "config", "i18n-tasks.yml"))
+        task.unused_keys
+      end
+    end
+
+    x.compare!
+  end
+
+  all_suites << [suite, "end_to_end/#{scale}"]
+end
+
+# ---------------------------------------------------------------------------
+# Scanner backend comparison: parser AST vs Prism on medium fixture
+# ---------------------------------------------------------------------------
+
+BenchHelper.header("Scanner backend: parser AST vs Prism (medium used_tree)")
+
+dir = BenchmarkFixtures.generate(:medium)
+
+backend_suite = Benchmark.ips do |x|
+  x.config(warmup: 2, time: 15)
+
+  x.report("used_tree — parser AST (medium)") do
+    Dir.chdir(dir) do
+      task = I18n::Tasks::BaseTask.new(
+        config_file: File.join(dir, "config", "i18n-tasks.yml"),
+        search: {scanners: [["::I18n::Tasks::Scanners::RubyScanner", {only: %w[*.rb], prism: nil}],
+          ["::I18n::Tasks::Scanners::ErbAstScanner", {only: %w[*.erb]}]]}
+      )
+      task.used_tree
+    end
+  end
+
+  x.report("used_tree — prism (medium)") do
+    Dir.chdir(dir) do
+      task = I18n::Tasks::BaseTask.new(
+        config_file: File.join(dir, "config", "i18n-tasks.yml"),
+        search: {scanners: [["::I18n::Tasks::Scanners::RubyScanner", {only: %w[*.rb], prism: "rails"}],
+          ["::I18n::Tasks::Scanners::ErbAstScanner", {only: %w[*.erb]}]]}
+      )
+      task.used_tree
+    end
+  end
+
+  x.compare!
+end
+
+all_suites << [backend_suite, "end_to_end/backend_comparison"]
+
+# ---------------------------------------------------------------------------
+# Memory profiling on the most realistic scale (medium, opt-in via --memory)
+# ---------------------------------------------------------------------------
+
+if MEMORY_PROFILE
+  dir = BenchmarkFixtures.generate(:medium)
+
+  BenchHelper.header("Memory profile — missing_keys (medium)")
+  MemoryProfiler.report do
+    Dir.chdir(dir) do
+      task = I18n::Tasks::BaseTask.new(config_file: File.join(dir, "config", "i18n-tasks.yml"))
+      task.missing_keys
+    end
+  end.pretty_print(scale_bytes: true, detailed_report: false)
+
+  BenchHelper.header("Memory profile — unused_keys (medium)")
+  MemoryProfiler.report do
+    Dir.chdir(dir) do
+      task = I18n::Tasks::BaseTask.new(config_file: File.join(dir, "config", "i18n-tasks.yml"))
+      task.unused_keys
+    end
+  end.pretty_print(scale_bytes: true, detailed_report: false)
+end
+
+# ---------------------------------------------------------------------------
+# Save / compare results
+# ---------------------------------------------------------------------------
+
+passed = true
+all_suites.each do |(suite, label)|
+  BenchHelper.save_results(suite, label) if SAVE_RESULTS
+  passed = false if COMPARE_RESULTS && !BenchHelper.compare_baseline(suite, label)
+end
+
+exit(1) if COMPARE_RESULTS && !passed