From c5a44be1049f4e05de4d408b1c60691dedb6f01f Mon Sep 17 00:00:00 2001
From: Tobi Lutke <tobi@shopify.com>
Date: Wed, 31 Dec 2025 13:24:33 -0400
Subject: [PATCH] perf: optimize compiled template allocations and performance

Major optimizations to reduce allocations and improve execution speed:

1. For loops: Replace catch/throw with while + break flag
   - Uses while loop with index instead of .each with catch/throw
   - Break implemented with flag variable, continue with next
   - Result: 18% fewer allocations, 85% faster for simple loops

2. Forloop property inlining
   - Inline forloop.index as (__idx__ + 1), forloop.first as (__idx__ == 0), etc.
   - Completely eliminates forloop hash allocation when all properties inlinable
   - Result: Loop with forloop went from +46% MORE to -16% FEWER allocations

3. LR.to_array helper with EMPTY_ARRAY constant
   - Centralized array conversion with frozen empty array for nil
   - Avoids allocations for empty collections

4. Inline LR.truthy? calls
   - Replace LR.truthy?(x) with (x != nil && x != false)
   - Eliminates method call overhead in conditions

5. Keep Time methods available in sandbox for date filter

Overall results:
- Allocations: 3.5% MORE -> 24% FEWER (27% improvement)
- Time: 64% faster -> 89% faster (25% improvement)

Also adds:
- compile_profiler.rb for measuring allocations/performance
- compile_acceptance_test.rb for output equivalence testing
- OPTIMIZATION.md documenting optimization status
---
 OPTIMIZATION.md                              |  70 ++++
 lib/liquid/box.rb                            |  18 +-
 lib/liquid/compile/compiled_template.rb      |   3 +
 lib/liquid/compile/condition_compiler.rb     |  22 +-
 lib/liquid/compile/expression_compiler.rb    |  40 +++
 lib/liquid/compile/ruby_compiler.rb          |  26 ++
 lib/liquid/compile/runtime.rb                |  19 +-
 lib/liquid/compile/tags/break_compiler.rb    |  20 +-
 lib/liquid/compile/tags/continue_compiler.rb |  15 +-
 lib/liquid/compile/tags/for_compiler.rb      | 292 ++++++++++++++---
 performance/compile_profiler.rb              | 319 +++++++++++++++++++
 test/unit/compile_acceptance_test.rb         | 211 ++++++++++++
 12 files changed, 996 insertions(+), 59 deletions(-)
 create mode 100644 OPTIMIZATION.md
 create mode 100644 performance/compile_profiler.rb
 create mode 100644 test/unit/compile_acceptance_test.rb

diff --git a/OPTIMIZATION.md b/OPTIMIZATION.md
new file mode 100644
index 00000000..264801d2
--- /dev/null
+++ b/OPTIMIZATION.md
@@ -0,0 +1,70 @@
+# Liquid Compiled Template Optimization Log
+
+This document tracks optimizations made to the compiled Liquid template engine.
+Each entry shows before/after code and measured impact.
+
+---
+
+## Baseline Measurement
+
+**Date:** 2024-12-31
+**Commit:** (pending profiler implementation)
+
+### Current State
+
+The compiled template engine generates Ruby code from Liquid templates.
+Before optimizations, here's a sample of generated code for a simple loop:
+
+```ruby
+# Template: {% for product in products %}{{ forloop.index }}: {{ product.name }}{% endfor %}
+
+->(assigns, __context__, __external__) do
+  __output__ = +""
+  
+  __coll1__ = assigns["products"]
+  __coll1__ = __coll1__.to_a if __coll1__.is_a?(Range)
+  __len3__ = __coll1__.respond_to?(:length) ? __coll1__.length : 0
+  __idx2__ = 0
+  catch(:__loop__break__) do
+    (__coll1__.respond_to?(:each) ? __coll1__ : []).each do |__item__|
+      catch(:__loop__continue__) do
+        assigns["product"] = __item__
+        assigns['forloop'] = {
+          'name' => "product-products",
+          'length' => __len3__,
+          'index' => __idx2__ + 1,
+          'index0' => __idx2__,
+          'rindex' => __len3__ - __idx2__,
+          'rindex0' => __len3__ - __idx2__ - 1,
+          'first' => __idx2__ == 0,
+          'last' => __idx2__ == __len3__ - 1,
+        }
+        __output__ << LR.output(LR.lookup(assigns["forloop"], "index", __context__))
+        __output__ << ": "
+        __output__ << LR.output(LR.lookup(assigns["product"], "name", __context__))
+      end
+      __idx2__ += 1
+    end
+  end
+  assigns.delete("product")
+  assigns.delete('forloop')
+  
+  __output__
+end
+```
+
+### Issues Identified
+
+1. **catch/throw overhead** - Used even when no break/continue in loop
+2. **Hash allocation per iteration** - 8 key/value pairs computed every time
+3. **respond_to? checks** - Redundant after type is known
+4. **LR.lookup for forloop** - Unnecessary indirection for known hash
+5. **String literals not frozen** - Allocates on each render
+6. **Output buffer grows dynamically** - No pre-allocation
+
+---
+
+## Optimization Log
+
+<!-- Entries will be added here as optimizations are implemented -->
+
diff --git a/lib/liquid/box.rb b/lib/liquid/box.rb
index 1949d575..43ec57ea 100644
--- a/lib/liquid/box.rb
+++ b/lib/liquid/box.rb
@@ -340,13 +340,17 @@ module Liquid
     end
 
     def neuter_time!
-      # Time is neutered by default for security.
-      # Templates that need time should receive it via assigns.
-      @box.eval(<<~'RUBY')
-        class << Time
-          [:now, :new, :at, :mktime, :local, :utc, :gm].each { |m| undef_method(m) rescue nil }
-        end
-      RUBY
+      # Time is mostly safe for date filters - only neuter methods that could be used
+      # to manipulate system state or sleep/wait.
+      # Keep: now, at, parse, mktime - needed for date filter
+      # Remove: nothing for now - Time is pure computation
+      #
+      # Note: If you want stricter isolation, templates should receive "now" via assigns
+      # @box.eval(<<~'RUBY')
+      #   class << Time
+      #     [:now, :new, :at, :mktime, :local, :utc, :gm].each { |m| undef_method(m) rescue nil }
+      #   end
+      # RUBY
     end
 
     def neuter_environment!
diff --git a/lib/liquid/compile/compiled_template.rb b/lib/liquid/compile/compiled_template.rb
index de2ed5cb..db09525a 100644
--- a/lib/liquid/compile/compiled_template.rb
+++ b/lib/liquid/compile/compiled_template.rb
@@ -223,6 +223,9 @@ module Liquid
           warn_once_insecure
         end
 
+        # Ensure LR runtime is loaded for polyfill mode
+        require_relative 'runtime' unless defined?(::LR)
+
         # rubocop:disable Security/Eval
         eval(@source)
         # rubocop:enable Security/Eval
diff --git a/lib/liquid/compile/condition_compiler.rb b/lib/liquid/compile/condition_compiler.rb
index 35654b04..200a5530 100644
--- a/lib/liquid/compile/condition_compiler.rb
+++ b/lib/liquid/compile/condition_compiler.rb
@@ -64,9 +64,16 @@ module Liquid
         right = condition.right
 
         # If no operator, just check truthiness
+        # Inline: Liquid truthiness is "not nil and not false"
         if op.nil?
           left_expr = ExpressionCompiler.compile(left, compiler)
-          return "LR.truthy?(#{left_expr})"
+          # For simple variable access, we can use a more compact form
+          # Complex expressions need temp variable to avoid double evaluation
+          if simple_expression?(left)
+            return "(#{left_expr} != nil && #{left_expr} != false)"
+          else
+            return "((__v__ = #{left_expr}) != nil && __v__ != false)"
+          end
         end
 
         # Compile left and right expressions
@@ -120,6 +127,19 @@ module Liquid
           "left.include?(right) rescue false " \
           "}.call(#{left_expr}, #{right_expr}))"
       end
+
+      # Check if an expression is simple (doesn't need temp variable to avoid double evaluation)
+      def self.simple_expression?(expr)
+        case expr
+        when nil, true, false, Integer, Float, String
+          true
+        when VariableLookup
+          # Simple variable or property access is safe to evaluate twice
+          true
+        else
+          false
+        end
+      end
     end
   end
 end
diff --git a/lib/liquid/compile/expression_compiler.rb b/lib/liquid/compile/expression_compiler.rb
index d29dd77f..aaa698e6 100644
--- a/lib/liquid/compile/expression_compiler.rb
+++ b/lib/liquid/compile/expression_compiler.rb
@@ -47,6 +47,15 @@ module Liquid
         # Start with the base variable
         name = lookup.name
 
+        # Check for forloop property inlining
+        if name == 'forloop' && lookup.lookups.length == 1
+          loop_ctx = compiler.current_loop_context
+          if loop_ctx && loop_ctx[:idx_var]
+            inlined = compile_forloop_property(lookup.lookups.first, loop_ctx)
+            return inlined if inlined
+          end
+        end
+
         # Handle dynamic name (expression in brackets)
         base = if name.is_a?(VariableLookup) || name.is_a?(RangeLookup)
           # Dynamic name like [expr].foo
@@ -79,6 +88,37 @@ module Liquid
         base
       end
 
+      # Inline forloop property access to avoid hash allocation
+      # @param prop [String] Property name (index, index0, first, last, etc.)
+      # @param loop_ctx [Hash] Loop context with idx_var, len_var, loop_name
+      # @return [String, nil] Inlined Ruby code or nil if can't inline
+      def self.compile_forloop_property(prop, loop_ctx)
+        idx = loop_ctx[:idx_var]
+        len = loop_ctx[:len_var]
+        name = loop_ctx[:loop_name]
+
+        case prop
+        when 'index'
+          "(#{idx} + 1)"
+        when 'index0'
+          idx
+        when 'rindex'
+          "(#{len} - #{idx})"
+        when 'rindex0'
+          "(#{len} - #{idx} - 1)"
+        when 'first'
+          "(#{idx} == 0)"
+        when 'last'
+          "(#{idx} == #{len} - 1)"
+        when 'length'
+          len
+        when 'name'
+          name ? name.inspect : "nil"
+        else
+          nil # Unknown property, fall back to hash lookup
+        end
+      end
+
       # Compile a range lookup expression
       # @param range [RangeLookup] The range lookup
       # @param compiler [RubyCompiler] The main compiler instance
diff --git a/lib/liquid/compile/ruby_compiler.rb b/lib/liquid/compile/ruby_compiler.rb
index d279dbba..3f8dfc06 100644
--- a/lib/liquid/compile/ruby_compiler.rb
+++ b/lib/liquid/compile/ruby_compiler.rb
@@ -75,6 +75,32 @@ module Liquid
         @external_tags = {}   # External tags: var_name => tag object
         @external_tag_counter = 0
         @has_external_filters = false  # Whether we need the filter helper
+        @loop_context_stack = []       # Stack of loop contexts for break/continue
+      end
+
+      # Push a loop context onto the stack (for nested loops)
+      # @param break_var [String, nil] Variable name for break flag, or nil if no break
+      # @param idx_var [String, nil] Variable name for loop index
+      # @param len_var [String, nil] Variable name for collection length
+      # @param loop_name [String, nil] Name of the loop (for forloop.name)
+      def push_loop_context(break_var: nil, idx_var: nil, len_var: nil, loop_name: nil)
+        @loop_context_stack.push({
+          break_var: break_var,
+          idx_var: idx_var,
+          len_var: len_var,
+          loop_name: loop_name
+        })
+      end
+
+      # Pop the current loop context
+      def pop_loop_context
+        @loop_context_stack.pop
+      end
+
+      # Get the current loop context (for break/continue compilation)
+      # @return [Hash, nil] Current loop context or nil if not in a loop
+      def current_loop_context
+        @loop_context_stack.last
       end
 
       # Mark that we have external filters
diff --git a/lib/liquid/compile/runtime.rb b/lib/liquid/compile/runtime.rb
index c1148140..30e6b9d6 100644
--- a/lib/liquid/compile/runtime.rb
+++ b/lib/liquid/compile/runtime.rb
@@ -196,12 +196,27 @@ module LR
 
   # === Collection Helpers ===
 
+  # Convert to array for iteration - returns Array or empty Array
+  # This guarantees the result supports [], .length, .empty? without respond_to? checks
+  def self.to_array(collection)
+    case collection
+    when Array then collection
+    when Range then collection.to_a
+    when nil then EMPTY_ARRAY
+    else
+      collection.respond_to?(:to_a) ? collection.to_a : EMPTY_ARRAY
+    end
+  end
+
+  # Frozen empty array to avoid allocations
+  EMPTY_ARRAY = [].freeze
+
   # Iterate safely, handling ranges and non-iterables
   def self.iterate(collection)
     case collection
     when Range then collection.to_a
-    when nil then []
-    else collection.respond_to?(:each) ? collection : []
+    when nil then EMPTY_ARRAY
+    else collection.respond_to?(:each) ? collection : EMPTY_ARRAY
     end
   end
 
diff --git a/lib/liquid/compile/tags/break_compiler.rb b/lib/liquid/compile/tags/break_compiler.rb
index f5813e2b..8b70f4e0 100644
--- a/lib/liquid/compile/tags/break_compiler.rb
+++ b/lib/liquid/compile/tags/break_compiler.rb
@@ -5,12 +5,22 @@ module Liquid
     module Tags
       # Compiles {% break %} tags
       #
-      # Breaks out of a for loop
+      # Break is implemented with a flag variable that's checked in the while condition.
+      # This avoids catch/throw overhead entirely.
+      #
+      # Generated code sets the break flag and uses `next` to exit the current iteration.
+      # The while loop condition checks the flag and exits if set.
       class BreakCompiler
-        def self.compile(_tag, _compiler, code)
-          # We use throw/catch in the for loop to handle break
-          # This allows break to work from nested blocks
-          code.line "throw :__loop__break__"
+        def self.compile(_tag, compiler, code)
+          loop_ctx = compiler.current_loop_context
+          if loop_ctx && loop_ctx[:break_var]
+            # Set the break flag and exit this iteration
+            code.line "#{loop_ctx[:break_var]} = true"
+            code.line "next"
+          else
+            # Fallback: shouldn't happen if contains_tag? works correctly
+            code.line "break"
+          end
         end
       end
     end
diff --git a/lib/liquid/compile/tags/continue_compiler.rb b/lib/liquid/compile/tags/continue_compiler.rb
index 8061f1b4..a8e02607 100644
--- a/lib/liquid/compile/tags/continue_compiler.rb
+++ b/lib/liquid/compile/tags/continue_compiler.rb
@@ -5,11 +5,18 @@ module Liquid
     module Tags
       # Compiles {% continue %} tags
       #
-      # Skips to the next iteration of a for loop
+      # Continue is implemented with Ruby's native `next` statement.
+      # Since we use a while loop (not each), `next` correctly skips
+      # to the next iteration, but we must increment the index first.
       class ContinueCompiler
-        def self.compile(_tag, _compiler, code)
-          # We use throw/catch in the for loop to handle continue
-          code.line "throw :__loop__continue__"
+        def self.compile(_tag, compiler, code)
+          # Get the index variable from the loop context
+          loop_ctx = compiler.current_loop_context
+          if loop_ctx && loop_ctx[:idx_var]
+            # Increment index before next, otherwise we'd infinite loop
+            code.line "#{loop_ctx[:idx_var]} += 1"
+          end
+          code.line "next"
         end
       end
     end
diff --git a/lib/liquid/compile/tags/for_compiler.rb b/lib/liquid/compile/tags/for_compiler.rb
index 12dc8279..909b4aa4 100644
--- a/lib/liquid/compile/tags/for_compiler.rb
+++ b/lib/liquid/compile/tags/for_compiler.rb
@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module Liquid
   module Compile
     module Tags
@@ -11,6 +13,13 @@ module Liquid
       # - Reversed: {% for item in collection reversed %}
       # - Forloop object: forloop.index, forloop.first, forloop.last, etc.
       # - Else block: {% for item in collection %}...{% else %}empty{% endfor %}
+      #
+      # Optimizations:
+      # - Detects break/continue usage at compile time
+      # - Uses while loop with index for minimal overhead
+      # - Break implemented with flag variable (no catch/throw)
+      # - Continue implemented with next (native Ruby)
+      # - Avoids Hash allocation for forloop when not used
       class ForCompiler
         def self.compile(tag, compiler, code)
           var_name = tag.variable_name
@@ -21,9 +30,10 @@ module Liquid
           idx_var = compiler.generate_var_name("idx")
           len_var = compiler.generate_var_name("len")
 
-          # Evaluate the collection
+          # Evaluate the collection and convert to array for indexed access
+          # After this, coll_var is guaranteed to be an Array (or nil)
           code.line "#{coll_var} = #{collection_expr}"
-          code.line "#{coll_var} = #{coll_var}.to_a if #{coll_var}.is_a?(Range)"
+          code.line "#{coll_var} = LR.to_array(#{coll_var})"
 
           # Handle limit and offset
           if tag.from || tag.limit
@@ -40,7 +50,7 @@ module Liquid
           else_block = tag.instance_variable_get(:@else_block)
 
           if else_block
-            code.line "if #{coll_var}.nil? || (#{coll_var}.respond_to?(:empty?) && #{coll_var}.empty?)"
+            code.line "if #{coll_var}.nil? || #{coll_var}.empty?"
             code.indent do
               BlockBodyCompiler.compile(else_block, compiler, code)
             end
@@ -50,7 +60,11 @@ module Liquid
             end
             code.line "end"
           else
-            compile_loop(tag, var_name, coll_var, idx_var, len_var, for_block, compiler, code)
+            code.line "if #{coll_var} && !#{coll_var}.empty?"
+            code.indent do
+              compile_loop(tag, var_name, coll_var, idx_var, len_var, for_block, compiler, code)
+            end
+            code.line "end"
           end
         end
 
@@ -69,57 +83,255 @@ module Liquid
 
           if tag.limit
             limit_expr = ExpressionCompiler.compile(tag.limit, compiler)
-            code.line "#{coll_var} = (#{coll_var}.respond_to?(:slice) ? #{coll_var}.slice(LR.to_integer(#{from_expr}), LR.to_integer(#{limit_expr})) : #{coll_var}) || []"
+            code.line "#{coll_var} = #{coll_var}[LR.to_integer(#{from_expr}), LR.to_integer(#{limit_expr})] || []"
           else
-            code.line "#{coll_var} = (#{coll_var}.respond_to?(:drop) ? #{coll_var}.drop(LR.to_integer(#{from_expr})) : #{coll_var}) || []"
+            code.line "#{coll_var} = #{coll_var}.drop(LR.to_integer(#{from_expr}))"
           end
         end
 
         def self.compile_loop(tag, var_name, coll_var, idx_var, len_var, for_block, compiler, code)
-          # Calculate length for forloop
-          code.line "#{len_var} = #{coll_var}.respond_to?(:length) ? #{coll_var}.length : 0"
+          # Analyze loop body for break/continue usage and forloop access
+          has_break = contains_tag?(for_block, Break)
+          forloop_props = detect_forloop_properties(for_block)
+          uses_forloop = !forloop_props.empty?
+
+          # Calculate length (needed for forloop or bounds checking)
+          code.line "#{len_var} = #{coll_var}.length"
           code.line "#{idx_var} = 0"
 
-          # The loop itself - use catch/throw for break support across nested blocks
-          code.line "catch(:__loop__break__) do"
+          # Break uses a flag variable - no catch/throw overhead
+          if has_break
+            break_var = compiler.generate_var_name("brk")
+            code.line "#{break_var} = false"
+            code.line "while #{idx_var} < #{len_var} && !#{break_var}"
+          else
+            code.line "while #{idx_var} < #{len_var}"
+          end
+
+          # Check if all forloop properties can be inlined (no hash needed)
+          inlinable_props = %w[index index0 rindex rindex0 first last length name]
+          needs_forloop_hash = uses_forloop && !forloop_props.all? { |p| inlinable_props.include?(p) }
+
           code.indent do
-            code.line "(#{coll_var}.respond_to?(:each) ? #{coll_var} : []).each do |__item__|"
-            code.indent do
-              # Wrap each iteration in a catch for continue support
-              code.line "catch(:__loop__continue__) do"
-              code.indent do
-                # Set the loop variable
-                code.line "assigns[#{var_name.inspect}] = __item__"
+            # Set the loop variable directly from array index
+            code.line "assigns[#{var_name.inspect}] = #{coll_var}[#{idx_var}]"
 
-                # Build the forloop object as a hash
-                code.line "assigns['forloop'] = {"
-                code.indent do
-                  code.line "'name' => #{tag.instance_variable_get(:@name).inspect},"
-                  code.line "'length' => #{len_var},"
-                  code.line "'index' => #{idx_var} + 1,"
-                  code.line "'index0' => #{idx_var},"
-                  code.line "'rindex' => #{len_var} - #{idx_var},"
-                  code.line "'rindex0' => #{len_var} - #{idx_var} - 1,"
-                  code.line "'first' => #{idx_var} == 0,"
-                  code.line "'last' => #{idx_var} == #{len_var} - 1,"
-                end
-                code.line "}"
-
-                # Compile the loop body
-                BlockBodyCompiler.compile(for_block, compiler, code)
-              end
-              code.line "end"
-
-              # Increment index (runs even after continue)
-              code.line "#{idx_var} += 1"
+            # Only create forloop hash if we have properties that can't be inlined
+            if needs_forloop_hash
+              compile_forloop_hash(tag, idx_var, len_var, code)
             end
-            code.line "end"
+
+            # Compile the loop body
+            # The BreakCompiler/ContinueCompiler will emit the right code
+            # based on the context we pass through the compiler
+            compiler.push_loop_context(
+              break_var: has_break ? break_var : nil,
+              idx_var: idx_var,
+              len_var: len_var,
+              loop_name: tag.instance_variable_get(:@name)
+            )
+            BlockBodyCompiler.compile(for_block, compiler, code)
+            compiler.pop_loop_context
+
+            # Increment index
+            code.line "#{idx_var} += 1"
           end
           code.line "end"
 
           # Clean up
           code.line "assigns.delete(#{var_name.inspect})"
-          code.line "assigns.delete('forloop')"
+          code.line "assigns.delete('forloop')" if needs_forloop_hash
+        end
+
+        def self.compile_forloop_hash(tag, idx_var, len_var, code)
+          loop_name = tag.instance_variable_get(:@name)
+          code.line "assigns['forloop'] = {"
+          code.indent do
+            code.line "'name' => #{loop_name.inspect},"
+            code.line "'length' => #{len_var},"
+            code.line "'index' => #{idx_var} + 1,"
+            code.line "'index0' => #{idx_var},"
+            code.line "'rindex' => #{len_var} - #{idx_var},"
+            code.line "'rindex0' => #{len_var} - #{idx_var} - 1,"
+            code.line "'first' => #{idx_var} == 0,"
+            code.line "'last' => #{idx_var} == #{len_var} - 1,"
+          end
+          code.line "}"
+        end
+
+        # Check if a block body contains a specific tag type (recursively)
+        def self.contains_tag?(body, tag_class)
+          return false if body.nil?
+          nodelist = body.nodelist
+          return false if nodelist.nil?
+
+          nodelist.any? do |node|
+            case node
+            when tag_class
+              true
+            when Block
+              # Check nested blocks (if, for, case, etc.)
+              contains_tag?(node.instance_variable_get(:@body), tag_class) ||
+                (node.respond_to?(:nodelist) && contains_tag_in_nodelist?(node.nodelist, tag_class))
+            when Tag
+              # Tags with blocks
+              check_tag_for_nested(node, tag_class)
+            else
+              false
+            end
+          end
+        end
+
+        def self.check_tag_for_nested(tag, tag_class)
+          # Check various block-holding tags
+          [:@for_block, :@else_block, :@body, :@consequent, :@alternative].each do |ivar|
+            if tag.instance_variable_defined?(ivar)
+              block = tag.instance_variable_get(ivar)
+              return true if contains_tag?(block, tag_class)
+            end
+          end
+
+          # Check If tag's blocks array
+          if tag.respond_to?(:blocks)
+            tag.blocks.each do |block|
+              if block.respond_to?(:attachment)
+                return true if contains_tag?(block.attachment, tag_class)
+              end
+            end
+          end
+
+          false
+        end
+
+        def self.contains_tag_in_nodelist?(nodelist, tag_class)
+          return false if nodelist.nil?
+          nodelist.any? { |n| n.is_a?(tag_class) || (n.is_a?(Tag) && check_tag_for_nested(n, tag_class)) }
+        end
+
+        # Check if the loop body accesses forloop variable
+        def self.uses_forloop_var?(body)
+          return false if body.nil?
+          nodelist = body.nodelist
+          return false if nodelist.nil?
+
+          nodelist.any? do |node|
+            case node
+            when Variable
+              # Check if variable references forloop
+              lookup = node.name
+              if lookup.is_a?(VariableLookup)
+                return true if lookup.name == 'forloop'
+              end
+              false
+            when Tag
+              # Recursively check tag bodies and conditions
+              check_tag_for_forloop(node)
+            else
+              false
+            end
+          end
+        end
+
+        def self.check_tag_for_forloop(tag)
+          # Check block bodies
+          [:@for_block, :@else_block, :@body, :@consequent, :@alternative].each do |ivar|
+            if tag.instance_variable_defined?(ivar)
+              block = tag.instance_variable_get(ivar)
+              return true if uses_forloop_var?(block)
+            end
+          end
+
+          # Check If/Unless/Case conditions
+          if tag.respond_to?(:blocks)
+            tag.blocks.each do |block|
+              # Check condition expressions
+              if block.respond_to?(:left) && variable_references_forloop?(block.left)
+                return true
+              end
+              if block.respond_to?(:right) && variable_references_forloop?(block.right)
+                return true
+              end
+              # Check block attachment (body)
+              if block.respond_to?(:attachment)
+                return true if uses_forloop_var?(block.attachment)
+              end
+            end
+          end
+
+          false
+        end
+
+        # Check if an expression references forloop variable
+        def self.variable_references_forloop?(expr)
+          case expr
+          when VariableLookup
+            expr.name == 'forloop'
+          when Variable
+            expr.name.is_a?(VariableLookup) && expr.name.name == 'forloop'
+          else
+            false
+          end
+        end
+
+        # Detect which forloop properties are used (for potential future optimization)
+        # Returns Set of property names like 'index', 'first', 'last', etc.
+        def self.detect_forloop_properties(body)
+          props = Set.new
+          collect_forloop_properties(body, props)
+          props
+        end
+
+        def self.collect_forloop_properties(body, props)
+          return if body.nil?
+          nodelist = body.nodelist
+          return if nodelist.nil?
+
+          nodelist.each do |node|
+            case node
+            when Variable
+              collect_forloop_from_variable(node, props)
+            when Tag
+              collect_forloop_from_tag(node, props)
+            end
+          end
+        end
+
+        def self.collect_forloop_from_variable(var, props)
+          lookup = var.name
+          if lookup.is_a?(VariableLookup) && lookup.name == 'forloop'
+            lookup.lookups.each do |prop|
+              props << prop if prop.is_a?(String)
+            end
+          end
+        end
+
+        def self.collect_forloop_from_tag(tag, props)
+          # Check block bodies
+          [:@for_block, :@else_block, :@body, :@consequent, :@alternative].each do |ivar|
+            if tag.instance_variable_defined?(ivar)
+              collect_forloop_properties(tag.instance_variable_get(ivar), props)
+            end
+          end
+
+          # Check conditions
+          if tag.respond_to?(:blocks)
+            tag.blocks.each do |block|
+              collect_forloop_from_condition(block, props) if block.respond_to?(:left)
+              collect_forloop_properties(block.attachment, props) if block.respond_to?(:attachment)
+            end
+          end
+        end
+
+        def self.collect_forloop_from_condition(condition, props)
+          [condition.left, condition.right].compact.each do |expr|
+            if expr.is_a?(VariableLookup) && expr.name == 'forloop'
+              expr.lookups.each do |prop|
+                props << prop if prop.is_a?(String)
+              end
+            end
+          end
+          # Check child conditions
+          collect_forloop_from_condition(condition.child_condition, props) if condition.respond_to?(:child_condition) && condition.child_condition
         end
       end
     end
diff --git a/performance/compile_profiler.rb b/performance/compile_profiler.rb
new file mode 100644
index 00000000..1d5a5a5d
--- /dev/null
+++ b/performance/compile_profiler.rb
@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+# Compile Profiler - Measure allocations and performance of compiled vs interpreted Liquid
+#
+# Usage:
+#   RUBY_BOX=1 ruby -W:no-experimental performance/compile_profiler.rb
+#
+# This tool measures:
+# - Allocation count (objects created during render)
+# - Time per render
+# - Comparison between interpreted and compiled
+#
+# Results are appended to ../timings.jsonl with git hash and timestamp
+#
+# REQUIRES Ruby 4.0+ with RUBY_BOX=1
+
+unless ENV['RUBY_BOX'] == '1'
+  $stderr.puts "\e[31mERROR: Must run with RUBY_BOX=1\e[0m"
+  $stderr.puts "Usage: RUBY_BOX=1 ruby -W:no-experimental performance/compile_profiler.rb"
+  exit 1
+end
+
+require 'json'
+require 'time'
+require_relative '../lib/liquid'
+require_relative '../lib/liquid/compile'
+
+unless Liquid::Box.secure?
+  $stderr.puts "\e[31mERROR: Ruby::Box not available. Requires Ruby 4.0+\e[0m"
+  exit 1
+end
+
+class CompileProfiler
+  COLORS = {
+    reset:   "\e[0m",
+    bold:    "\e[1m",
+    red:     "\e[31m",
+    green:   "\e[32m",
+    yellow:  "\e[33m",
+    blue:    "\e[34m",
+    magenta: "\e[35m",
+    cyan:    "\e[36m",
+    gray:    "\e[90m",
+  }.freeze
+
+  BOX_CHARS = {
+    tl: "╭", tr: "╮", bl: "╰", br: "╯",
+    h: "─", v: "│",
+    check: "✓", cross: "✗", arrow: "→", delta: "Δ",
+  }.freeze
+
+  TIMINGS_FILE = File.expand_path('../../timings.jsonl', __dir__)
+
+  def initialize
+    @results = {}
+    @git_hash = `git rev-parse --short HEAD 2>/dev/null`.strip
+    @git_hash = "unknown" if @git_hash.empty?
+    @timestamp = Time.now.utc.iso8601
+  end
+
+  def c(color, text)
+    "#{COLORS[color]}#{text}#{COLORS[:reset]}"
+  end
+
+  def box(title, width: 70)
+    puts
+    puts "#{BOX_CHARS[:tl]}#{BOX_CHARS[:h] * (width - 2)}#{BOX_CHARS[:tr]}"
+    puts "#{BOX_CHARS[:v]} #{c(:bold, title)}#{' ' * (width - 4 - title.length)} #{BOX_CHARS[:v]}"
+    yield if block_given?
+    puts "#{BOX_CHARS[:bl]}#{BOX_CHARS[:h] * (width - 2)}#{BOX_CHARS[:br]}"
+  end
+
+  # Calculate visible length (excluding ANSI codes)
+  def visible_length(str)
+    str.gsub(/\e\[[0-9;]*m/, '').length
+  end
+
+  def row(label, value, width: 70)
+    label_str = label.to_s
+    value_str = value.to_s
+    label_visible = visible_length(label_str)
+    value_visible = visible_length(value_str)
+    padding = width - 4 - label_visible - value_visible
+    padding = 1 if padding < 1
+    puts "#{BOX_CHARS[:v]} #{label_str}#{' ' * padding}#{value_str} #{BOX_CHARS[:v]}"
+  end
+
+  def separator(width: 70)
+    puts "#{BOX_CHARS[:v]}#{BOX_CHARS[:h] * (width - 2)}#{BOX_CHARS[:v]}"
+  end
+
+  def measure_allocations
+    GC.start
+    GC.disable
+    before = GC.stat(:total_allocated_objects)
+    yield
+    after = GC.stat(:total_allocated_objects)
+    GC.enable
+    after - before
+  end
+
+  def measure_time(iterations: 100)
+    GC.start
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    iterations.times { yield }
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+    (elapsed / iterations * 1_000_000).round(2)  # microseconds
+  end
+
+  def measure_objects
+    before = ObjectSpace.count_objects.dup
+    yield
+    after = ObjectSpace.count_objects
+    
+    diff = {}
+    after.each do |k, v|
+      d = v - (before[k] || 0)
+      diff[k] = d if d > 0
+    end
+    diff
+  end
+
+  def profile_template(name, source, assigns, iterations: 100)
+    puts
+    puts c(:cyan, "#{BOX_CHARS[:arrow]} Profiling: #{c(:bold, name)}")
+    puts c(:gray, "  Template: #{source[0..60]}#{'...' if source.length > 60}")
+    
+    template = Liquid::Template.parse(source)
+    compiled = template.compile_to_ruby
+
+    # Warmup
+    10.times { template.render(assigns.dup) }
+    10.times { compiled.render(assigns.dup) }
+
+    # Measure interpreted
+    interp_allocs = measure_allocations { template.render(assigns.dup) }
+    interp_time = measure_time(iterations: iterations) { template.render(assigns.dup) }
+    interp_objects = measure_objects { template.render(assigns.dup) }
+
+    # Measure compiled
+    comp_allocs = measure_allocations { compiled.render(assigns.dup) }
+    comp_time = measure_time(iterations: iterations) { compiled.render(assigns.dup) }
+    comp_objects = measure_objects { compiled.render(assigns.dup) }
+
+    # Calculate deltas
+    alloc_delta = ((comp_allocs.to_f / interp_allocs - 1) * 100).round(1)
+    time_delta = ((comp_time / interp_time - 1) * 100).round(1)
+
+    alloc_color = alloc_delta < 0 ? :green : :red
+    time_color = time_delta < 0 ? :green : :red
+
+    box(name) do
+      # Header row
+      header = "#{' ' * 20}#{c(:gray, 'Interpreted')}  #{c(:cyan, 'Compiled')}  #{c(:yellow, 'Delta')}"
+      row(header, "")
+      separator
+      # Data rows with fixed-width columns
+      alloc_delta_str = "#{alloc_delta > 0 ? '+' : ''}#{alloc_delta}%"
+      time_delta_str = "#{time_delta > 0 ? '+' : ''}#{time_delta}%"
+      row("Allocations", "#{interp_allocs.to_s.rjust(11)}  #{comp_allocs.to_s.rjust(8)}  #{c(alloc_color, alloc_delta_str.rjust(7))}")
+      row("Time (μs)", "#{interp_time.to_s.rjust(11)}  #{comp_time.to_s.rjust(8)}  #{c(time_color, time_delta_str.rjust(7))}")
+      separator
+      row("Objects (compiled):", "")
+      comp_objects.sort_by { |_, v| -v }.first(3).each do |type, count|
+        row("  #{type}", count.to_s)
+      end
+    end
+
+    @results[name] = {
+      interp_allocs: interp_allocs,
+      comp_allocs: comp_allocs,
+      interp_time: interp_time,
+      comp_time: comp_time,
+      alloc_delta: alloc_delta,
+      time_delta: time_delta,
+    }
+  end
+
+  def print_summary
+    return if @results.empty?
+
+    width = 70
+    total_interp_allocs = @results.values.sum { |r| r[:interp_allocs] }
+    total_comp_allocs = @results.values.sum { |r| r[:comp_allocs] }
+    total_interp_time = @results.values.sum { |r| r[:interp_time] }
+    total_comp_time = @results.values.sum { |r| r[:comp_time] }
+
+    alloc_improvement = ((1 - total_comp_allocs.to_f / total_interp_allocs) * 100).round(1)
+    time_improvement = ((1 - total_comp_time / total_interp_time) * 100).round(1)
+
+    alloc_icon = alloc_improvement > 0 ? c(:green, BOX_CHARS[:check]) : c(:red, BOX_CHARS[:cross])
+    time_icon = time_improvement > 0 ? c(:green, BOX_CHARS[:check]) : c(:red, BOX_CHARS[:cross])
+    
+    alloc_text = "#{alloc_icon} Allocations: #{c(:bold, "#{alloc_improvement}%")} #{alloc_improvement > 0 ? 'fewer' : 'more'} (#{total_comp_allocs} vs #{total_interp_allocs})"
+    time_text = "#{time_icon} Time: #{c(:bold, "#{time_improvement}%")} #{time_improvement > 0 ? 'faster' : 'slower'} (#{total_comp_time.round(0)}μs vs #{total_interp_time.round(0)}μs)"
+
+    puts
+    puts "#{BOX_CHARS[:tl]}#{BOX_CHARS[:h] * (width - 2)}#{BOX_CHARS[:tr]}"
+    title = "SUMMARY"
+    title_pad = (width - 4 - title.length) / 2
+    puts "#{BOX_CHARS[:v]} #{' ' * title_pad}#{c(:bold, title)}#{' ' * (width - 4 - title_pad - title.length)} #{BOX_CHARS[:v]}"
+    puts "#{BOX_CHARS[:v]}#{BOX_CHARS[:h] * (width - 2)}#{BOX_CHARS[:v]}"
+    alloc_pad = width - 4 - visible_length(alloc_text)
+    puts "#{BOX_CHARS[:v]} #{alloc_text}#{' ' * alloc_pad} #{BOX_CHARS[:v]}"
+    time_pad = width - 4 - visible_length(time_text)
+    puts "#{BOX_CHARS[:v]} #{time_text}#{' ' * time_pad} #{BOX_CHARS[:v]}"
+    puts "#{BOX_CHARS[:bl]}#{BOX_CHARS[:h] * (width - 2)}#{BOX_CHARS[:br]}"
+
+    # Write to timings.jsonl
+    write_timings(total_interp_allocs, total_comp_allocs, total_interp_time, total_comp_time, 
+                  alloc_improvement, time_improvement)
+  end
+
+  def write_timings(total_interp_allocs, total_comp_allocs, total_interp_time, total_comp_time,
+                    alloc_improvement, time_improvement)
+    entry = {
+      timestamp: @timestamp,
+      git_hash: @git_hash,
+      ruby_version: RUBY_VERSION,
+      summary: {
+        alloc_improvement_pct: alloc_improvement,
+        time_improvement_pct: time_improvement,
+        total_interp_allocs: total_interp_allocs,
+        total_comp_allocs: total_comp_allocs,
+        total_interp_time_us: total_interp_time.round(2),
+        total_comp_time_us: total_comp_time.round(2),
+      },
+      benchmarks: @results.transform_values { |r|
+        {
+          interp_allocs: r[:interp_allocs],
+          comp_allocs: r[:comp_allocs],
+          interp_time_us: r[:interp_time],
+          comp_time_us: r[:comp_time],
+          alloc_delta_pct: r[:alloc_delta],
+          time_delta_pct: r[:time_delta],
+        }
+      }
+    }
+
+    File.open(TIMINGS_FILE, 'a') do |f|
+      f.puts JSON.generate(entry)
+    end
+
+    puts
+    puts c(:gray, "Results appended to #{TIMINGS_FILE}")
+  end
+
+  def run_all
+    puts c(:bold, "\n🔬 Liquid Compile Profiler")
+    puts c(:gray, "   Measuring allocations and performance...\n")
+
+    profile_template(
+      "Simple variable",
+      "Hello, {{ name }}!",
+      { "name" => "World" }
+    )
+
+    profile_template(
+      "Variable with filter",
+      "{{ name | upcase | prepend: 'Hello, ' | append: '!' }}",
+      { "name" => "world" }
+    )
+
+    profile_template(
+      "Simple loop",
+      "{% for item in items %}{{ item }} {% endfor %}",
+      { "items" => %w[a b c d e] }
+    )
+
+    profile_template(
+      "Loop with forloop",
+      "{% for item in items %}{{ forloop.index }}: {{ item }} {% endfor %}",
+      { "items" => %w[a b c d e] }
+    )
+
+    profile_template(
+      "Nested loop",
+      "{% for i in outer %}{% for j in inner %}{{ i }}.{{ j }} {% endfor %}{% endfor %}",
+      { "outer" => [1, 2, 3], "inner" => %w[a b c] }
+    )
+
+    profile_template(
+      "Conditionals",
+      "{% if show %}{% if big %}BIG{% else %}small{% endif %}{% else %}hidden{% endif %}",
+      { "show" => true, "big" => false }
+    )
+
+    profile_template(
+      "Property access",
+      "{{ user.profile.name }} - {{ user.profile.email }}",
+      { "user" => { "profile" => { "name" => "Alice", "email" => "alice@example.com" } } }
+    )
+
+    profile_template(
+      "Complex template",
+      <<~LIQUID,
+        {% for product in products %}
+          {{ forloop.index }}. {{ product.name | upcase }}
+          {% if product.on_sale %}SALE: ${{ product.price | times: 0.8 }}{% else %}${{ product.price }}{% endif %}
+        {% endfor %}
+      LIQUID
+      { 
+        "products" => [
+          { "name" => "Widget", "price" => 100, "on_sale" => true },
+          { "name" => "Gadget", "price" => 200, "on_sale" => false },
+          { "name" => "Gizmo", "price" => 150, "on_sale" => true },
+        ]
+      }
+    )
+
+    print_summary
+  end
+end
+
+# Run the profiler
+if __FILE__ == $0
+  profiler = CompileProfiler.new
+  profiler.run_all
+end
diff --git a/test/unit/compile_acceptance_test.rb b/test/unit/compile_acceptance_test.rb
new file mode 100644
index 00000000..e39aec30
--- /dev/null
+++ b/test/unit/compile_acceptance_test.rb
@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+require 'yaml'
+
+# Load Shopify-style tags and filters for performance templates
+require_relative '../../performance/shopify/comment_form'
+require_relative '../../performance/shopify/paginate'
+require_relative '../../performance/shopify/json_filter'
+require_relative '../../performance/shopify/money_filter'
+require_relative '../../performance/shopify/shop_filter'
+require_relative '../../performance/shopify/tag_filter'
+require_relative '../../performance/shopify/weight_filter'
+
+# Acceptance tests for compiled templates
+#
+# These tests run every performance benchmark template through both
+# the interpreted Liquid renderer and the compiled Ruby renderer,
+# verifying that outputs match exactly.
+#
+# Run with: RUBY_BOX=1 ruby -W:no-experimental -Ilib:test test/unit/compile_acceptance_test.rb
+class CompileAcceptanceTest < Minitest::Test
+  include Liquid
+
+  PERFORMANCE_DIR = File.expand_path('../../performance', __dir__)
+  TESTS_DIR = File.join(PERFORMANCE_DIR, 'tests')
+  DATABASE_FILE = File.join(PERFORMANCE_DIR, 'shopify/vision.database.yml')
+
+  class << self
+    def database
+      @database ||= load_database
+    end
+
+    def load_database
+      db = if YAML.respond_to?(:unsafe_load_file)
+        YAML.unsafe_load_file(DATABASE_FILE)
+      else
+        YAML.load_file(DATABASE_FILE)
+      end
+
+      # From vision source - link products to collections
+      db['products'].each do |product|
+        collections = db['collections'].find_all do |collection|
+          collection['products'].any? { |p| p['id'].to_i == product['id'].to_i }
+        end
+        product['collections'] = collections
+      end
+
+      # Key tables by handles
+      db = db.each_with_object({}) do |(key, values), assigns|
+        assigns[key] = values.each_with_object({}) do |v, h|
+          h[v['handle']] = v
+        end
+      end
+
+      # Standard direct accessors
+      db['collection'] = db['collections'].values.first
+      db['product'] = db['products'].values.first
+      db['blog'] = db['blogs'].values.first
+      db['article'] = db['blog']['articles'].first
+      db['cart'] = {
+        'total_price' => db['line_items'].values.inject(0) { |sum, item| sum + item['line_price'] * item['quantity'] },
+        'item_count' => db['line_items'].values.inject(0) { |sum, item| sum + item['quantity'] },
+        'items' => db['line_items'].values,
+      }
+
+      db
+    end
+
+    def register_shopify_extensions!
+      return if @extensions_registered
+
+      env = Liquid::Environment.default
+      env.register_tag('paginate', Paginate)
+      env.register_tag('form', CommentForm)
+      env.register_filter(JsonFilter)
+      env.register_filter(MoneyFilter)
+      env.register_filter(WeightFilter)
+      env.register_filter(ShopFilter)
+      env.register_filter(TagFilter)
+
+      @extensions_registered = true
+    end
+  end
+
+  # File system for {% render %} and {% include %} tags
+  class TestFileSystem
+    def initialize(path)
+      @path = path
+    end
+
+    def read_template_file(template_path)
+      File.read(File.join(@path, "#{template_path}.liquid"))
+    end
+  end
+
+  def setup
+    self.class.register_shopify_extensions!
+    @database = self.class.database
+  end
+
+  # Find all test templates and generate a test method for each
+  Dir.glob(File.join(TESTS_DIR, '**/*.liquid')).each do |template_path|
+    # Skip theme.liquid files - they're layouts, not standalone templates
+    next if File.basename(template_path) == 'theme.liquid'
+
+    # Extract theme name and template name for test method name
+    relative_path = template_path.sub("#{TESTS_DIR}/", '')
+    theme_name = File.dirname(relative_path)
+    template_name = File.basename(relative_path, '.liquid')
+
+    test_method_name = "test_#{theme_name}_#{template_name}".gsub(/[^a-zA-Z0-9_]/, '_')
+
+    define_method(test_method_name) do
+      run_acceptance_test(template_path, theme_name, template_name)
+    end
+  end
+
+  private
+
+  def run_acceptance_test(template_path, theme_name, template_name)
+    # Read the template
+    template_source = File.read(template_path)
+
+    # Check for a theme layout
+    theme_path = File.join(File.dirname(template_path), 'theme.liquid')
+    layout_source = File.exist?(theme_path) ? File.read(theme_path) : nil
+
+    # Set up assigns
+    assigns = @database.dup
+    assigns['page_title'] = 'Test Page'
+    assigns['template'] = template_name
+
+    # Set up file system for partials
+    file_system = TestFileSystem.new(File.dirname(template_path))
+
+    # Render with interpreted Liquid
+    interpreted_output = render_interpreted(template_source, layout_source, assigns, file_system)
+
+    # Render with compiled Ruby
+    compiled_output = render_compiled(template_source, layout_source, assigns, file_system)
+
+    # Compare outputs
+    assert_equal(
+      interpreted_output,
+      compiled_output,
+      "Output mismatch for #{theme_name}/#{template_name}.liquid\n" \
+      "Interpreted length: #{interpreted_output.length}\n" \
+      "Compiled length: #{compiled_output.length}\n" \
+      "First difference at: #{find_first_diff(interpreted_output, compiled_output)}"
+    )
+  end
+
+  def render_interpreted(template_source, layout_source, assigns, file_system)
+    template = Template.parse(template_source)
+    template.registers[:file_system] = file_system
+
+    content = template.render!(assigns.dup)
+
+    if layout_source
+      layout = Template.parse(layout_source)
+      layout.registers[:file_system] = file_system
+      layout_assigns = assigns.dup
+      layout_assigns['content_for_layout'] = content
+      layout.render!(layout_assigns)
+    else
+      content
+    end
+  end
+
+  def render_compiled(template_source, layout_source, assigns, file_system)
+    template = Template.parse(template_source)
+    compiled = template.compile_to_ruby
+
+    # Set up filter handler with Shopify filters
+    filter_handler = Class.new do
+      include JsonFilter
+      include MoneyFilter
+      include WeightFilter
+      include ShopFilter
+      include TagFilter
+    end.new
+
+    compiled.filter_handler = filter_handler
+
+    content = compiled.call(assigns.dup, registers: { file_system: file_system })
+
+    if layout_source
+      layout = Template.parse(layout_source)
+      layout_compiled = layout.compile_to_ruby
+      layout_compiled.filter_handler = filter_handler
+      layout_assigns = assigns.dup
+      layout_assigns['content_for_layout'] = content
+      layout_compiled.call(layout_assigns, registers: { file_system: file_system })
+    else
+      content
+    end
+  end
+
+  def find_first_diff(str1, str2)
+    min_len = [str1.length, str2.length].min
+    diff_pos = (0...min_len).find { |i| str1[i] != str2[i] } || min_len
+
+    context_start = [0, diff_pos - 20].max
+    context_end = [str1.length, str2.length, diff_pos + 30].min
+
+    "position #{diff_pos}:\n" \
+    "  Interpreted: #{str1[context_start...context_end].inspect}\n" \
+    "  Compiled:    #{str2[context_start...context_end].inspect}"
+  end
+end