ruby_raider 1.1.4 → 3.0.0

data/lib/generators/menu_generator.rb

@@ -3,8 +3,6 @@
 require 'tty-prompt'
 require_relative '../generators/invoke_generators'
 
-# :reek:FeatureEnvy { enabled: false }
-# :reek:UtilityFunction { enabled: false }
 class MenuGenerator
   attr_reader :prompt, :name
 
@@ -32,10 +30,16 @@ class MenuGenerator
       automation: options[:automation],
       framework: options[:framework],
       ci_platform: options[:ci_platform],
+      reporter: options[:reporter],
+      accessibility: options[:accessibility],
+      visual: options[:visual],
+      performance: options[:performance],
+      ruby_version: options[:ruby_version],
       name: @name
     }
     generate_framework(structure)
     system "cd #{name} && gem install bundler && bundle install"
+    offer_desktop_download
   end
 
   def choose_mobile_platform
@@ -49,29 +53,137 @@ class MenuGenerator
 
   private
 
+  def offer_desktop_download
+    return unless prompt.yes?('Would you like to download Raider Desktop (GUI companion app)?')
+
+    require_relative '../utilities/desktop_downloader'
+    version = DesktopDownloader.latest_version
+    unless version
+      prompt.warn('Could not reach GitHub releases. You can download it later with: raider u desktop')
+      return
+    end
+
+    prompt.say("Downloading Raider Desktop v#{version} for #{DesktopDownloader.platform_display_name}...")
+    result = DesktopDownloader.download
+    if result
+      prompt.ok("Downloaded to: #{result}")
+    else
+      prompt.warn('No release found for your platform. Visit: https://github.com/RaiderHQ/raider_desktop/releases')
+    end
+  end
+
   def select_test_framework(automation)
     prompt.select('Please select your test framework') do |menu|
       menu.choice :Cucumber, -> { select_ci_platform('Cucumber', automation) }
       menu.choice :Rspec, -> { select_ci_platform('Rspec', automation) }
+      menu.choice :Minitest, -> { select_ci_platform('Minitest', automation) }
       menu.choice :Quit, -> { exit }
     end
   end
 
-  FrameworkOptions = Struct.new(:automation, :framework, :ci_platform)
+  FrameworkOptions = Struct.new(:automation, :framework, :ci_platform, :reporter, :accessibility, :visual, :performance,
+                                :ruby_version)
 
   def create_framework_options(params)
-    FrameworkOptions.new(params[:automation], params[:framework], params[:ci_platform])
+    FrameworkOptions.new(params[:automation], params[:framework], params[:ci_platform], params[:reporter],
+                         params[:accessibility], params[:visual], params[:performance], params[:ruby_version])
+  end
+
+  def select_reporter(framework, automation_type, ci_platform = nil)
+    prompt.select('Select your test reporter') do |menu|
+      menu.choice :Allure, -> { select_accessibility(framework, automation_type, ci_platform, 'allure') }
+      menu.choice :JUnit, -> { select_accessibility(framework, automation_type, ci_platform, 'junit') }
+      menu.choice :JSON, -> { select_accessibility(framework, automation_type, ci_platform, 'json') }
+      menu.choice :Both, -> { select_accessibility(framework, automation_type, ci_platform, 'both') }
+      menu.choice :All, -> { select_accessibility(framework, automation_type, ci_platform, 'all') }
+      menu.choice :None, -> { select_accessibility(framework, automation_type, ci_platform, 'none') }
+      menu.choice :Quit, -> { exit }
+    end
+  end
+
+  def select_accessibility(framework, automation_type, ci_platform = nil, reporter = nil)
+    return create_framework(framework, automation_type, ci_platform:, reporter:) if mobile_automation?(automation_type)
+
+    prompt.select('Add accessibility testing (axe)?') do |menu|
+      menu.choice :Yes, -> { select_visual(framework, automation_type, ci_platform, reporter, accessibility: true) }
+      menu.choice :No, -> { select_visual(framework, automation_type, ci_platform, reporter) }
+      menu.choice :Quit, -> { exit }
+    end
+  end
+
+  def select_visual(framework, automation_type, ci_platform = nil, reporter = nil, accessibility: false)
+    prompt.select('Add visual regression testing?') do |menu|
+      menu.choice :Yes, lambda {
+        select_performance(framework, automation_type, ci_platform, reporter, accessibility:, visual: true)
+      }
+      menu.choice :No, lambda {
+        select_performance(framework, automation_type, ci_platform, reporter, accessibility:)
+      }
+      menu.choice :Quit, -> { exit }
+    end
+  end
+
+  def select_performance(framework, automation_type, ci_platform = nil, reporter = nil, accessibility: false,
+                         visual: false)
+    prompt.select('Add Lighthouse performance auditing?') do |menu|
+      menu.choice :Yes, lambda {
+        select_ruby_version(framework, automation_type, ci_platform:, reporter:, accessibility:, visual:,
+                            performance: true)
+      }
+      menu.choice :No, lambda {
+        select_ruby_version(framework, automation_type, ci_platform:, reporter:, accessibility:, visual:)
+      }
+      menu.choice :Quit, -> { exit }
+    end
+  end
+
+  def select_ruby_version(framework, automation_type, ci_platform: nil, reporter: nil, accessibility: false,
+                          visual: false, performance: false)
+    prompt.select('Select Ruby version for your project') do |menu|
+      menu.choice :'3.4 (latest)', lambda {
+        create_framework(framework, automation_type, ci_platform:, reporter:, accessibility:, visual:, performance:,
+                         ruby_version: '3.4')
+      }
+      menu.choice :'3.3', lambda {
+        create_framework(framework, automation_type, ci_platform:, reporter:, accessibility:, visual:, performance:,
+                         ruby_version: '3.3')
+      }
+      menu.choice :'3.2', lambda {
+        create_framework(framework, automation_type, ci_platform:, reporter:, accessibility:, visual:, performance:,
+                         ruby_version: '3.2')
+      }
+      menu.choice :'3.1', lambda {
+        create_framework(framework, automation_type, ci_platform:, reporter:, accessibility:, visual:, performance:,
+                         ruby_version: '3.1')
+      }
+      menu.choice :Quit, -> { exit }
+    end
+  end
+
+  def mobile_automation?(automation_type)
+    %w[ios android cross_platform].include?(automation_type)
   end
 
-  def create_framework(framework, automation_type, ci_platform = nil)
+  def create_framework(framework, automation_type, ci_platform: nil, reporter: nil, accessibility: false,
+                       visual: false, performance: false, ruby_version: nil)
     options = create_framework_options(automation: automation_type,
                                        framework: framework.downcase,
-                                       ci_platform:)
+                                       ci_platform:,
+                                       reporter:,
+                                       accessibility:,
+                                       visual:,
+                                       performance:,
+                                       ruby_version:)
 
     puts 'Chosen Options:'
     puts "  Automation Type: #{options[:automation]}"
     puts "  Framework: #{options[:framework]}"
     puts "  CI Platform: #{options[:ci_platform]}" if options[:ci_platform]
+    puts "  Reporter: #{options[:reporter]}" if options[:reporter]
+    puts '  Accessibility: enabled' if options[:accessibility]
+    puts '  Visual Testing: enabled' if options[:visual]
+    puts '  Performance Auditing: enabled' if options[:performance]
+    puts "  Ruby Version: #{options[:ruby_version]}" if options[:ruby_version]
 
     set_up_framework(options)
     prompt.say("You have chosen to use #{framework} with #{automation_type}")
@@ -92,17 +204,16 @@ class MenuGenerator
 
   def automation_options(menu)
     menu.choice :Selenium, -> { choose_test_framework('selenium') }
+    menu.choice :Capybara, -> { choose_test_framework('capybara') }
     menu.choice :Appium, -> { choose_test_framework('appium') }
     menu.choice :Watir, -> { choose_test_framework('watir') }
-    menu.choice :Applitools, -> { choose_test_framework('applitools') }
-    menu.choice :Axe, -> { choose_test_framework('axe') }
   end
 
   def select_ci_platform(framework, automation)
     prompt.select('Would you like to configure CI?') do |menu|
-      menu.choice :'Github Actions', -> { create_framework(framework, automation, 'github') }
-      menu.choice :'Gitlab CI/CD', -> { create_framework(framework, automation, 'gitlab') }
-      menu.choice :No, -> { create_framework(framework, automation) }
+      menu.choice :'Github Actions', -> { select_reporter(framework, automation, 'github') }
+      menu.choice :'Gitlab CI/CD', -> { select_reporter(framework, automation, 'gitlab') }
+      menu.choice :No, -> { select_reporter(framework, automation) }
       menu.choice :Quit, -> { exit }
     end
   end

data/lib/generators/minitest/minitest_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../generator'
+
+class MinitestGenerator < Generator
+  def generate_login_test
+    return unless web?
+
+    template('test.tt', "#{name}/test/test_login_page.rb")
+  end
+
+  def generate_pdp_test
+    return unless mobile?
+
+    template('test.tt', "#{name}/test/test_pdp_page.rb")
+  end
+
+  def generate_visual_test
+    return unless visual_addon? && web?
+
+    template('visual_test.tt', "#{name}/test/test_visual.rb")
+  end
+
+  def generate_accessibility_test
+    return unless axe_addon? && web?
+
+    template('accessibility_test.tt', "#{name}/test/test_accessibility.rb")
+  end
+
+  def generate_performance_test
+    return unless lighthouse_addon? && web?
+
+    template('performance_test.tt', "#{name}/test/test_performance.rb")
+  end
+end

data/lib/generators/minitest/templates/accessibility_test.tt

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/test_helper'
+
+class TestAccessibility < Minitest::Test
+  def setup
+    super
+    <% if capybara? -%>
+visit '/'
+    <% elsif watir? -%>
+browser.goto 'https://raider-test-site.onrender.com/'
+    <% else -%>
+driver.get 'https://raider-test-site.onrender.com/'
+    <% end -%>
+  end
+
+  def test_no_accessibility_violations_on_page
+    <% if capybara? -%>
+assert_axe_clean page
+    <% elsif watir? -%>
+assert_axe_clean browser.driver
+    <% else -%>
+assert_axe_clean driver
+    <% end -%>
+  end
+end

data/lib/generators/minitest/templates/performance_test.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/test_helper'
+require_relative '../helpers/performance_helper'
+
+class TestPerformance < Minitest::Test
+  include PerformanceHelper
+
+  def test_meets_performance_threshold
+    result = assert_performance_above('https://raider-test-site.onrender.com/', threshold: 0.7)
+
+    refute_equal :error, result[:status],
+      "Lighthouse error: #{result[:message]}"
+
+    assert result[:passed],
+      "Performance below threshold (#{result[:threshold]}): #{result[:scores]}"
+  end
+end

data/lib/generators/minitest/templates/test.tt

@@ -0,0 +1,64 @@
+<%- if selenium_based? || watir? || capybara? -%>
+# frozen_string_literal: true
+
+require_relative '../helpers/test_helper'
+require_relative '../models/model_factory'
+require_relative '../page_objects/pages/account'
+require_relative '../page_objects/pages/login'
+
+# Uncomment for interactive debugging:
+# require 'debug'    # Ruby's built-in debugger (binding.break)
+# require 'pry'      # Pry debugger (binding.pry)
+
+<%- if selenium_based? || watir? || capybara? -%>
+class TestLogin < Minitest::Test
+  def setup
+    @user = ModelFactory.for('users')['registered user']
+    @login_page = <% if capybara? -%>Login.new<% elsif watir? -%>Login.new(browser)<% else -%>Login.new(driver)<% end %>
+    @account_page = <% if capybara? -%>Account.new<% elsif watir? -%>Account.new(browser)<% else -%>Account.new(driver)<% end %>
+  end
+
+  def teardown
+    <%= partial('quit_driver', strip: true) %>
+  end
+
+  def test_login_with_right_credentials
+    # binding.break  # Uncomment to pause here and inspect state
+    @login_page.<% if capybara? -%>visit_page<% else -%>visit<% end %>
+    @login_page.login(@user['username'], @user['password'])
+    @account_page.<% if capybara? -%>visit_page<% else -%>visit<% end %>
+    assert_equal "Welcome back #{@user['name']}", @account_page.header.customer_name
+  end
+
+  def test_login_with_wrong_credentials
+    @login_page.<% if capybara? -%>visit_page<% else -%>visit<% end %>
+    @login_page.login(@user['username'], 'wrongPassword')
+    @login_page.<% if capybara? -%>visit_page<% else -%>visit<% end %>
+    assert_equal 'Login or register', @account_page.header.customer_name
+  end
+end
+<%- end -%>
+<%- else -%>
+<% if cross_platform? -%>
+require_relative '../helpers/appium_helper'
+<%- end -%>
+require_relative '../helpers/test_helper'
+require_relative '../page_objects/pages/home'
+require_relative '../page_objects/pages/pdp'
+
+class TestPdp < Minitest::Test
+  def setup
+    @home_page = Home.new(driver)
+    @pdp_page = Pdp.new(driver)
+  end
+
+  def teardown
+    driver.quit_driver
+  end
+
+  def test_shows_add_to_cart_button
+    @home_page.go_to_product_detail
+    assert_equal 'Add to Cart', @pdp_page.add_to_cart_text
+  end
+end
+<%- end -%>

data/lib/generators/minitest/templates/visual_test.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/test_helper'
+require_relative '../helpers/visual_helper'
+require_relative '../page_objects/pages/login'
+
+class TestVisualRegression < Minitest::Test
+  include VisualHelper
+
+  def setup
+    super
+    @login_page = <% if capybara? -%>Login.new<% elsif watir? -%>Login.new(browser)<% else -%>Login.new(driver)<% end %>
+  end
+
+  def test_login_page_matches_baseline
+    @login_page.<% if capybara? -%>visit_page<% else -%>visit<% end %>
+    screenshot_path = <% if capybara? -%>page.save_screenshot('tmp/visual_login.png')<% elsif watir? -%>browser.screenshot.save('tmp/visual_login.png')<% else -%>driver.save_screenshot('tmp/visual_login.png')<% end %>
+    result = compare_screenshot('login_page', screenshot_path)
+
+    refute_equal :mismatch, result[:status],
+      "Visual diff: #{(result[:diff].to_f * 100).round(2)}% difference. See: #{result[:diff_path]}"
+  end
+end

data/lib/generators/rspec/rspec_generator.rb

@@ -4,7 +4,7 @@ require_relative '../generator'
 
 class RspecGenerator < Generator
   def generate_login_spec
-    return unless web? && !visual?
+    return unless web?
 
     template('spec.tt', "#{name}/spec/login_page_spec.rb")
   end
@@ -15,9 +15,21 @@ class RspecGenerator < Generator
     template('spec.tt', "#{name}/spec/pdp_page_spec.rb")
   end
 
-  def generate_account_spec
-    return unless visual?
+  def generate_visual_spec
+    return unless visual_addon? && web?
 
-    template('spec.tt', "#{name}/spec/account_page_spec.rb")
+    template('visual_spec.tt', "#{name}/spec/visual_spec.rb")
+  end
+
+  def generate_accessibility_spec
+    return unless axe_addon? && web?
+
+    template('accessibility_spec.tt', "#{name}/spec/accessibility_spec.rb")
+  end
+
+  def generate_performance_spec
+    return unless lighthouse_addon? && web?
+
+    template('performance_spec.tt', "#{name}/spec/performance_spec.rb")
   end
 end

data/lib/generators/rspec/templates/accessibility_spec.tt

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/spec_helper'
+
+describe 'Accessibility' do
+  before do
+    <% if capybara? -%>
+visit '/'
+    <% elsif watir? -%>
+browser.goto 'https://raider-test-site.onrender.com/'
+    <% else -%>
+driver.get 'https://raider-test-site.onrender.com/'
+    <% end -%>
+  end
+
+  it 'has no accessibility violations on the page' do
+    <% if capybara? -%>
+expect(page).to be_axe_clean
+    <% elsif watir? -%>
+expect(browser.driver).to be_axe_clean
+    <% else -%>
+expect(driver).to be_axe_clean
+    <% end -%>
+  end
+end

data/lib/generators/rspec/templates/performance_spec.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/spec_helper'
+require_relative '../helpers/performance_helper'
+
+describe 'Performance Audit' do
+  include PerformanceHelper
+
+  it 'meets performance threshold' do
+    result = assert_performance_above('https://raider-test-site.onrender.com/', threshold: 0.7)
+
+    expect(result[:status]).not_to eq(:error),
+      "Lighthouse error: #{result[:message]}"
+
+    expect(result[:passed]).to be(true),
+      "Performance below threshold (#{result[:threshold]}): #{result[:scores]}"
+  end
+end

data/lib/generators/rspec/templates/spec.tt

@@ -1,4 +1,4 @@
-<%- if selenium_based? || watir? -%>
+<%- if selenium_based? || watir? || capybara? -%>
 # frozen_string_literal: true
 
 require_relative '../helpers/spec_helper'
@@ -6,43 +6,20 @@ require_relative '../models/model_factory'
 require_relative '../page_objects/pages/account'
 require_relative '../page_objects/pages/login'
 
-<%- if axe? %>
-describe 'Login' do
-  let(:login) { Login.new(driver) }
-  let(:account) { Account.new(driver) }
-  let(:user) { ModelFactory.for('users')['registered user'] }
-
-  before do
-    login.visit
-    login.log_as(user['username'], user['password'])
-  end
-
-  context 'with a login user on the account page' do
-    it 'no accessibility errors are present on the page' do
-      expect(account.page).to be_axe_clean
-    end
-
-    it 'no accessibility errors are present on the transaction history' do
-      transaction_history = '.dash-tile.dash-tile-balloon.clearfix'
-      expect(account.page).to be_axe_clean.within transaction_history
-    end
+# Uncomment for interactive debugging:
+# require 'debug'    # Ruby's built-in debugger (binding.break)
+# require 'pry'      # Pry debugger (binding.pry)
 
-    it 'no accessibility errors are present on the heading' do
-      heading = '.maintext'
-      expect(account.page).to be_axe_clean.within heading
-    end
-  end
-end
-<%- elsif selenium_based? || watir? -%>
+<%- if selenium_based? || watir? || capybara? -%>
 describe 'Login' do
   subject(:header) { account_page.header.customer_name }
 
   let(:user) { ModelFactory.for('users')['registered user'] }
-  let(:login_page) { Login.new(<% if watir? -%>browser<% else -%>driver<% end -%>) }
-  let(:account_page) { Account.new(<% if watir? -%>browser<% else -%>driver<% end -%>) }
+  let(:login_page) { <% if capybara? -%>Login.new<% elsif watir? -%>Login.new(browser)<% else -%>Login.new(driver)<% end -%> }
+  let(:account_page) { <% if capybara? -%>Account.new<% elsif watir? -%>Account.new(browser)<% else -%>Account.new(driver)<% end -%> }
 
   before do
-    login_page.visit
+    login_page.<% if capybara? -%>visit_page<% else -%>visit<% end %>
     login_page.login(user['username'], password)
   end
 
@@ -50,11 +27,9 @@ describe 'Login' do
     let(:password) { user['password'] }
 
     it 'can successfully log in' do
-    <%- if visual? -%>
-      check_page account_page
-    <%- else -%>
+      # binding.break  # Uncomment to pause here and inspect state
+      account_page.<% if capybara? -%>visit_page<% else -%>visit<% end %>
       expect(header).to eq "Welcome back #{user['name']}"
-    <%- end -%>
     end
   end
 
@@ -62,11 +37,8 @@ describe 'Login' do
     let(:password) { 'wrongPassword' }
 
     it 'cannot log in' do
-    <%- if visual? -%>
-      check_page login_page
-    <%- else -%>
+      login_page.<% if capybara? -%>visit_page<% else -%>visit<% end %>
       expect(header).to eq 'Login or register'
-    <%- end -%>
     end
   end
 end
@@ -86,8 +58,8 @@ class PdpSpec
     let(:pdp_page) { Pdp.new(driver) }
 
     it 'shows add to cart button' do
-      home_page.go_to_backpack_pdp
-      expect(pdp_page.add_to_cart_text).to eq 'Add To Cart'
+      home_page.go_to_product_detail
+      expect(pdp_page.add_to_cart_text).to eq 'Add to Cart'
     end
   end
 end

data/lib/generators/rspec/templates/visual_spec.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/spec_helper'
+require_relative '../helpers/visual_helper'
+require_relative '../page_objects/pages/login'
+
+describe 'Visual Regression' do
+  include VisualHelper
+
+  let(:login_page) { <% if capybara? -%>Login.new<% elsif watir? -%>Login.new(browser)<% else -%>Login.new(driver)<% end -%> }
+
+  it 'login page matches baseline' do
+    login_page.<% if capybara? -%>visit_page<% else -%>visit<% end %>
+    screenshot_path = <% if capybara? -%>page.save_screenshot('tmp/visual_login.png')<% elsif watir? -%>browser.screenshot.save('tmp/visual_login.png')<% else -%>driver.save_screenshot('tmp/visual_login.png')<% end %>
+    result = compare_screenshot('login_page', screenshot_path)
+
+    expect(result[:status]).not_to eq(:mismatch),
+      "Visual diff: #{(result[:diff].to_f * 100).round(2)}% difference. See: #{result[:diff_path]}"
+  end
+end

data/lib/generators/template_renderer/partial_cache.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'erb'
+require_relative 'partial_resolver'
+require_relative 'template_error'
+
+module TemplateRenderer
+  # Caches compiled ERB template objects with mtime-based invalidation
+  #
+  # Cache structure:
+  #   cache_key => { erb: ERB_object, mtime: Time, path: String }
+  #
+  # Cache keys include trim_mode to support different whitespace handling:
+  #   "screenshot:-" => ERB object with trim_mode: '-'
+  #   "screenshot:" => ERB object with no trim_mode
+  #
+  # Performance: ~10x speedup on cached renders (135ms → ~13.5ms)
+  class PartialCache
+    # Set to true during batch generation to skip File.mtime syscalls on cache hits
+    attr_accessor :batch_mode
+
+    def initialize(generator_class)
+      @cache = {}
+      @resolver = PartialResolver.new(generator_class)
+      @batch_mode = false
+    end
+
+    # Render a partial with caching
+    #
+    # @param name [String] Partial name (without .tt extension)
+    # @param binding [Binding] Binding context for ERB evaluation
+    # @param options [Hash] Rendering options
+    # @option options [String, nil] :trim_mode ERB trim mode ('-', '<>', etc.)
+    # @return [String] Rendered template content
+    # @raise [TemplateNotFoundError] If partial not found
+    # @raise [TemplateRenderError] If rendering fails
+    def render_partial(name, binding, options = {})
+      trim_mode = options[:trim_mode]
+      cache_key = build_cache_key(name, trim_mode)
+
+      # Resolve the partial path
+      path = @resolver.resolve(name, binding)
+
+      # Get from cache or compile
+      erb = get_or_compile(cache_key, path, trim_mode)
+
+      # Render with provided binding
+      erb.result(binding)
+    rescue Errno::ENOENT => e
+      raise TemplateNotFoundError.new(
+        "Partial '#{name}' not found",
+        partial_name: name,
+        searched_paths: @resolver.search_paths(name, binding),
+        original_error: e
+      )
+    rescue TemplateError
+      raise
+    rescue StandardError => e
+      # Catch ERB syntax errors or other rendering issues
+      raise TemplateRenderError.new(
+        e.message,
+        partial_name: name,
+        original_error: e
+      )
+    end
+
+    # Clear the entire cache (useful for testing)
+    def clear
+      @cache.clear
+    end
+
+    # Get cache statistics (useful for debugging/monitoring)
+    def stats
+      {
+        size: @cache.size,
+        entries: @cache.keys,
+        memory_estimate: estimate_cache_size
+      }
+    end
+
+    private
+
+    # Build cache key that includes trim_mode
+    def build_cache_key(name, trim_mode)
+      "#{name}:#{trim_mode}"
+    end
+
+    # Get cached ERB or compile and cache it.
+    # In batch_mode, skip File.mtime syscalls on cache hits since templates
+    # don't change mid-generation (~2-5ms saved per partial render).
+    def get_or_compile(cache_key, path, trim_mode)
+      cached = @cache[cache_key]
+
+      # Fast path: batch mode cache hit (skip mtime check)
+      return cached[:erb] if cached && @batch_mode
+
+      current_mtime = File.mtime(path)
+
+      # Cache miss or stale cache (file modified)
+      if cached.nil? || cached[:mtime] < current_mtime
+        erb = compile_template(path, trim_mode)
+        @cache[cache_key] = {
+          erb:,
+          mtime: current_mtime,
+          path:
+        }
+        return erb
+      end
+
+      # Cache hit
+      cached[:erb]
+    end
+
+    # Compile an ERB template
+    def compile_template(path, trim_mode)
+      content = File.read(path)
+      ERB.new(content, trim_mode:)
+    end
+
+    # Rough estimate of cache memory usage
+    # Each entry: ~2-10 KB (ERB object + metadata)
+    def estimate_cache_size
+      @cache.size * 5 * 1024 # Rough estimate: 5 KB per entry
+    end
+  end
+end