Engine: Add helpers to compare compiled/rendered outputs of the Engine (#774)

This commit adds comprehensive tooling to compare `Herb::Engine`'s
output against `Erubi::Engine` for both the compiled templates and the
rendered templates.

It introduces three CLI tools: `bin/compare` for full comparisons,
`bin/compare-compile` for compiled source comparisons, and
`bin/compare-render` for rendered output comparisons.

All tools use `difftastic` to provide rich diffs showing both
string-level and semantic differences (Ruby AST for compiled code, HTML
structure for rendered output).



<img width="2115" height="1411" alt="CleanShot 2025-11-03 at 21 17
47@2x"
src="https://github.com/user-attachments/assets/f5017f6e-d514-4c00-9ca9-9e1680795693"
/>

<img width="1246" height="934" alt="CleanShot 2025-11-03 at 21 17 40@2x"
src="https://github.com/user-attachments/assets/35ff4f15-04d1-4e37-99f7-74211f6543e4"
/>

---

It also adds these helpers in `snapshot_utils.rb` so we can also run the
comparison for all `assert_evaluated_snapshot` and
`assert_compiled_snapshot` in the test suite using
`COMPARE_WITH_ERUBI=true`

```
COMPARE_WITH_ERUBI=true mtest
COMPARE_WITH_ERUBI=true mtest test/engine/evaluation_test.rb
```

Erubi compatibility is critical for Herb's adoption. Erubi is the de
facto standard ERB implementation used across the Ruby ecosystem,
particularly in Rails.

These comparison helpers serve as both documentation and verification of
our compatibility commitment. They help catch regressions during
development and make it trivial to investigate any differences between
implementations.

Author: marcoroth

.rubocop.yml

@@ -12,6 +12,12 @@ Style/StringLiterals:
   Enabled: true
   EnforcedStyle: double_quotes
 
+Style/MixinUsage:
+  Exclude:
+    - bin/compare
+    - bin/compare-render
+    - bin/compare-compile
+
 Style/ClassAndModuleChildren:
   Enabled: false
 
@@ -94,6 +100,7 @@ Metrics/ModuleLength:
   Exclude:
     - test/**/*.rb
     - templates/**/*.rb
+    - bin/lib/compare_helpers.rb
 
 Metrics/BlockLength:
   Max: 30
@@ -160,6 +167,8 @@ Security/Eval:
     - lib/herb/cli.rb
     - test/**/*.rb
     - bin/erubi-render
+    - bin/compare-render
+    - bin/compare-render
 
 Security/MarshalLoad:
   Exclude:

Gemfile

@@ -7,6 +7,8 @@ gemspec
 gem "prism", github: "ruby/prism", tag: "v1.6.0"
 
 gem "actionview", "~> 8.0"
+gem "difftastic", "~> 0.7"
+gem "erubi"
 gem "lz_string"
 gem "maxitest"
 gem "minitest-difftastic", "~> 0.2"

Gemfile.lock

@@ -183,6 +183,8 @@ PLATFORMS
 
 DEPENDENCIES
   actionview (~> 8.0)
+  difftastic (~> 0.7)
+  erubi
   herb!
   lz_string
   maxitest

bin/compare

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "pathname"
+require "optparse"
+
+require_relative "lib/compare_helpers"
+
+include CompareHelpers
+
+def usage
+  puts "Usage: #{$PROGRAM_NAME} [options] <file>"
+  puts ""
+  puts "Compares an ERB template with both Herb and Erubi (compile and render)."
+  puts ""
+  puts "Options:"
+  puts "  --no-escape              Disable HTML escaping"
+  puts "  --escape                 Enable HTML escaping (default: false)"
+  puts "  -h, --help               Show this help message"
+  exit(1)
+end
+
+options = {}
+options[:escape] = false
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: #{$PROGRAM_NAME} [options] <file>"
+
+  opts.on("--no-escape", "Disable HTML escaping") do
+    options[:escape] = false
+  end
+
+  opts.on("--escape", "Enable HTML escaping") do
+    options[:escape] = true
+  end
+
+  opts.on("-h", "--help", "Show this help message") do
+    usage
+  end
+end.parse!
+
+file_path = ARGV[0]
+
+unless file_path
+  puts "Error: No file specified"
+  usage
+end
+
+unless File.exist?(file_path)
+  puts "Error: File '#{file_path}' not found"
+  exit(1)
+end
+
+bin_dir = File.expand_path(__dir__)
+
+template = File.read(file_path)
+show_template(file_path, template)
+
+args = []
+args << "--escape" if options[:escape]
+args << "--no-escape" unless options[:escape]
+args << "--no-template"
+args << file_path
+
+box_header("Compiled HTML+ERB Template Output")
+puts ""
+
+compile_result = system(File.join(bin_dir, "compare-compile"), *args)
+
+puts ""
+box_header("Rendered HTML+ERB Template Output")
+puts ""
+
+render_result = system(File.join(bin_dir, "compare-render"), *args)
+
+puts ""
+box_header("Summary")
+
+if render_result && compile_result
+  puts "✓ All comparisons passed!"
+  puts ""
+  puts "  • Rendered outputs match"
+  puts "  • Compiled sources match"
+  exit(0)
+elsif render_result
+  puts "⚠ Rendered outputs match, but compiled sources differ"
+  puts ""
+  puts "  • ✓ Rendered outputs match (what matters!)"
+  puts "  • ✗ Compiled sources differ (different formatting is OK)"
+  puts ""
+  puts "This is usually fine. Herb and Erubi format generated code differently,"
+  puts "but produce the same final output."
+  exit(0)
+else
+  puts "✗ Comparisons failed"
+  puts ""
+  puts "  • Rendered output: #{render_result ? "✓ Match" : "✗ Differ"}"
+  puts "  • Compiled source: #{compile_result ? "✓ Match" : "✗ Differ"}"
+  exit(1)
+end

bin/compare-compile

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "pathname"
+require "optparse"
+require_relative "lib/compare_helpers"
+
+include CompareHelpers
+
+def usage
+  puts "Usage: #{$PROGRAM_NAME} [options] <file>"
+  puts ""
+  puts "Compiles an ERB template with both Erubi::Engine and Herb::Engine and shows the diff."
+  puts ""
+  puts "Options:"
+  puts "  --no-escape              Disable HTML escaping"
+  puts "  --escape                 Enable HTML escaping (default: false)"
+  puts "  -h, --help               Show this help message"
+  exit(1)
+end
+
+options = {}
+options[:escape] = false
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: #{$PROGRAM_NAME} [options] <file>"
+  parse_common_options(opts, options) { usage }
+end.parse!
+
+options[:show_template] = true unless options.key?(:show_template)
+
+file_path = ARGV[0]
+
+unless file_path
+  puts "Error: No file specified"
+  usage
+end
+
+unless File.exist?(file_path)
+  puts "Error: File '#{file_path}' not found"
+  exit(1)
+end
+
+load_dependencies
+
+template = File.read(file_path)
+show_template(file_path, template) if options[:show_template]
+
+begin
+  herb_engine = Herb::Engine.new(template, options)
+  herb_src = herb_engine.src
+rescue StandardError => e
+  puts "Herb compile error: #{e.message}"
+  exit(1)
+end
+
+begin
+  erubi_engine = Erubi::Engine.new(template, options)
+  erubi_src = erubi_engine.src
+rescue StandardError => e
+  puts "Erubi compile error: #{e.message}"
+  exit(1)
+end
+
+herb_normalized = herb_src.gsub("__herb", "__engine")
+erubi_normalized = erubi_src.gsub("__erubi", "__engine")
+
+if herb_normalized == erubi_normalized
+  puts "✓ Compiled sources match (after normalization)!"
+  puts ""
+  puts "Herb output:"
+  puts herb_src
+  exit(0)
+elsif herb_src == erubi_src
+  puts "✓ Compiled sources match exactly!"
+  puts ""
+  puts "Output:"
+  puts herb_src
+  exit(0)
+else
+  puts "✗ Compiled sources differ!"
+  puts ""
+  puts ""
+
+  diff_output = diff_compiled_sources(erubi_src, herb_src)
+  puts diff_output if diff_output
+
+  exit(1)
+end

bin/compare-render

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "pathname"
+require "optparse"
+require_relative "lib/compare_helpers"
+
+include CompareHelpers
+
+def usage
+  puts "Usage: #{$PROGRAM_NAME} [options] <file>"
+  puts ""
+  puts "Renders an ERB template with both Erubi::Engine and Herb::Engine and shows the diff."
+  puts ""
+  puts "Options:"
+  puts "  --no-escape              Disable HTML escaping"
+  puts "  --escape                 Enable HTML escaping (default: false)"
+  puts "  -h, --help               Show this help message"
+  exit(1)
+end
+
+options = {}
+options[:escape] = false
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: #{$PROGRAM_NAME} [options] <file>"
+  parse_common_options(opts, options) { usage }
+end.parse!
+
+options[:show_template] = true unless options.key?(:show_template)
+
+file_path = ARGV[0]
+
+unless file_path
+  puts "Error: No file specified"
+  usage
+end
+
+unless File.exist?(file_path)
+  puts "Error: File '#{file_path}' not found"
+  exit(1)
+end
+
+load_dependencies
+
+template = File.read(file_path)
+show_template(file_path, template) if options[:show_template]
+
+begin
+  herb_engine = Herb::Engine.new(template, options)
+  herb_output = eval(herb_engine.src)
+rescue StandardError => e
+  puts "Herb render error: #{e.message}"
+  exit(1)
+end
+
+begin
+  erubi_engine = Erubi::Engine.new(template, options)
+  erubi_output = eval(erubi_engine.src)
+rescue StandardError => e
+  puts "Erubi render error: #{e.message}"
+  exit(1)
+end
+
+if herb_output == erubi_output
+  puts "✓ Outputs match!"
+  puts ""
+  puts "Output:"
+  puts herb_output
+  exit(0)
+else
+  puts "✗ Outputs differ!"
+  puts ""
+  puts ""
+
+  diff_output = diff_rendered_outputs(erubi_output, herb_output)
+  puts diff_output if diff_output
+
+  exit(1)
+end