Engine: Compile-time optimizations for Action View tag helpers

[marcoroth]

This pull request adds compile-time optimization support for Action View tag helpers to Herb::Engine.

When optimize: true is passed to Herb::Engine, the parser transforms Action View helper calls (tag.*, content_tag, link_to, image_tag, javascript_tag, javascript_include_tag, turbo_frame_tag) into their HTML equivalents at compile time, producing optimized Ruby output that avoids runtime helper dispatch.

When compile-time optimizations are enabled, the engine checks whether the template contains supported Action View helpers via the Herb::ActionView::HelperRegistry.supported method. If helpers are detected, the parser is invoked with action_view_helpers: true and transform_conditionals: true, which also handles postfix if/unless and ternary conditionals containing helper calls.

The pull request also includes comprehensive snapshot-based tests for all supported helpers, an assert_optimized_output_match helper that validates optimized output against both standard Herb and ActionView+Erubi to ensure the rendered output matches.

Additionally, we added a YAML-driven benchmark framework in bench/action_view/ with a bin/bench CLI for compile-time and render-time comparisons. Early benchmarks show render-time improvements of 3-22x depending on the template, with a realistic 192-line page layout rendering 22x faster, and a helper-heavy template with all static values reaching up to 150x faster.

The trade-off is compile time: Herb's parser is currently 10-90x slower than Erubi at compile time, so optimization adds overhead that needs to be amortized over multiple renders. But this is typically won back with 15-100 renders depending on template complexity and could also be done ahead of time, instead of the current on-the-fly approach used in Action View today.

Warning

Compile-time optimizations are experimental. Output may differ from standard ActionView rendering.

Resolves #653
Enables #1111

[pkg-pr-new]

npx https://pkg.pr.new/@herb-tools/formatter@1613

npx https://pkg.pr.new/@herb-tools/language-server@1613

npx https://pkg.pr.new/@herb-tools/linter@1613

commit: 9926177

[github-actions]

🌿 Interactive Playground and Documentation Preview

A preview deployment has been built for this pull request. Try out the changes live in the interactive playground:

• Playground Preview
• Documentation Preview
• Website Preview

---

_{🌱 Grown from commit 9926177}

---

✅ Preview deployment has been cleaned up.

[joelhawksley]

@marcoroth did you test this against cases where the consumer re-defines an ActionView helper, say to add additional security features to csrf_meta_tags? I'll need to track down what our cases look like, but I believe we have a few places where we add additional functionality. It could be pretty unfortunate if we stripped out a re-defined helper silently.

[marcoroth]

Hey @joelhawksley, this feature is very experimental and opt-in. This currently also only applies for the helpers that the registry marks as "supported":

❯ bin/console
irb(main):001> require "herb/action_view/helper_registry"
=> true
irb(main):002> Herb::ActionView::HelperRegistry.supported.map(&:name)
=> ["image_tag", "javascript_include_tag", "javascript_tag", "content_tag", "tag", "link_to", "turbo_frame_tag"]
irb(main):003>

But yes, there is currently a gap when you overwrite content_tag or any other helper. As of right now they would get compiled away. The idea I had in mind to catch cases like these was to introduce a new development-only transform visitor that compiles in some runtime inspections whenever we compile away a helper. So that it could tell you at runtime that the helper method that we compiled away wasn't the original one from ActionView.

So if you had this:

<%= tag.div do %>
  Content
<% end %>

it would currently compile this template with the compile-time optimizations to this:

bin/herb compile test.html.erb --optimize

__herb = ::Herb::Engine; _buf = ::String.new; _buf << '<div>
  Content
</div>'.freeze;
_buf.to_s

and I was thinking of adding a pre- or postamble in development/test to either raise, or have it collect the warnings and show them like we just did in #1660:

__herb = ::Herb::Engine; _buf = ::String.new; _buf << '<div>
  Content
</div>'.freeze;
_buf.to_s
+
+ raise "Helper was overwritten" if method(:tag).owner != Herb::ActionView::HelperRegistry.get(:tag).source

[joelhawksley]

Ah yep, that makes sense. I just poked around a little bit and we have overrides for about a dozen or so of the helpers, so it's definitely something we'd want to leave turned off by default until we can be 100% confident in avoiding a mismatch.

In general, I'd argue that a runtime check is insufficient, as it assumes that every line of ERB is executed in CI.

[marcoroth]

@joelhawksley I just opened #1664 so we don't loose track of this, thanks for the input!

In general, I'd argue that a runtime check is insufficient, as it assumes that every line of ERB is executed in CI.

Yeah, I agree. Though, it wouldn't need to execute every line of ERB since it's either added to the start/end of the file, so rendering the template once in any way would be sufficient to fire the check at least once.

But there might also be a potential other way to do this in a more static manner by instantiating an empty ActionView::ViewContext and check the Source Location of the defined helpers that way and add that to something like herb actionview check (introduced via #1663) or herb analyze.