herb 0.10.4 → 0.11.0

data/lib/herb/engine/visitors/instrumentation_visitor.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+# typed: false
+
+require_relative "../../visitor"
+require_relative "../../visitor/experimental"
+require_relative "../../visitor/context_aware"
+require_relative "../../visitor/context/origin"
+
+module Herb
+  class Engine
+    # Wraps every ERB tag in a call that says which tag is rendering, so that whatever happens
+    # while it renders can be attributed to it rather than to the template as a whole.
+    #
+    # This is half of a mechanism and does nothing by itself. It supplies where, and something else
+    # has to supply what. A template compiled with it and rendered with nothing watching records no
+    # entries at all, and only costs a call per tag. What makes it worth having is anything that
+    # calls `Herb::Engine::Runtime::Session.observe` while a tag is rendering:
+    #
+    #     require "herb/engine/visitors/instrumentation_visitor"
+    #
+    #     engine = Herb::Engine.new(source, visitors: [Herb::Engine::InstrumentationVisitor.new])
+    #
+    #     ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
+    #       Herb::Engine::Runtime::Session.observe(:queries, payload[:sql]) unless payload[:cached]
+    #     end
+    #
+    #     session = Herb::Engine::Runtime::Session.capture { render(engine.src) }
+    #
+    #     session.measure(:queries, origin: "Herb Engine", code: "sql-queries") do |queries|
+    #       "#{queries.size} SQL queries"
+    #     end
+    #     #=> app/views/posts/_card.html.erb:7:8: [sql-queries] 3 SQL queries
+    #
+    # Nothing about that subscription is Herb's, which is the point. Because what gets watched is
+    # decided at render time rather than compiled in, adding a producer never means recompiling a
+    # template, and Herb never has to ship a class per thing worth watching.
+    #
+    # A tag that opens a block, or that assigns to a local, is framed from the outside rather than
+    # wrapped, because wrapping either one would change what the template means: a block would lose
+    # its body, and an assignment would bind inside the wrapper instead of the template.
+    #
+    class InstrumentationVisitor < Herb::Visitor
+      extend Herb::Visitor::Experimental
+      include Herb::Visitor::ContextAware
+
+      recommended_parser_option render_nodes: true
+      required_parser_option track_locations: true
+      experimental "Instrumentation is experimental as it instruments every ERB tag."
+
+      SESSION = "::Herb::Engine::Runtime::Session"
+      ARRAY_PROPERTIES = [:children, :body, :statements].freeze
+      NODE_PROPERTIES = [:subsequent, :else_clause, :rescue_clause, :ensure_clause].freeze
+
+      ASSIGNMENT_NODES = [
+        :LocalVariableWriteNode,
+        :LocalVariableOperatorWriteNode,
+        :LocalVariableOrWriteNode,
+        :LocalVariableAndWriteNode,
+        :MultiWriteNode
+      ].freeze
+
+      #: () -> bool
+      def self.rewrites_erb_source?
+        true
+      end
+
+      #: (?capture_output: (bool | ^(String) -> boolish | Regexp | Array[untyped])?) -> void
+      def initialize(capture_output: nil)
+        super()
+
+        @capture_everything = capture_output == true
+        @capture_output = (capture_output == true ? [] : Array(capture_output)) #: Array[untyped]
+      end
+
+      def visit_document_node(node)
+        @file = context.relative_file_path
+
+        super
+
+        instrument(node)
+
+        frame_render(node)
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      private
+
+      def frame_render(node)
+        template = render_arguments(context.relative_file_path)
+
+        node.children.unshift(erb_node(node, "<%", "#{SESSION}.enter_render(#{template}); begin"))
+        node.children.push(erb_node(node, "<%", "ensure; #{SESSION}.leave_render; end"))
+
+        nil
+      end
+
+      def instrument(node)
+        ARRAY_PROPERTIES.each do |property|
+          next unless node.respond_to?(property) && node.send(property).is_a?(Array)
+
+          rewrite(node.send(property))
+        end
+
+        NODE_PROPERTIES.each do |property|
+          next unless node.respond_to?(property) && node.send(property)
+
+          instrument(node.send(property))
+        end
+      end
+
+      def rewrite(nodes)
+        nodes.replace(nodes.flat_map { |node| rewrite_node(node) })
+      end
+
+      #: (Herb::AST::Node, Herb::Visitor::Context::Origin::Entry) -> Array[Herb::AST::Node]
+      def rewrite_import(node, entry)
+        outer = @file
+        @file = entry.file
+
+        instrument(node)
+
+        @file = outer
+
+        body = node.send(:body) #: Array[Herb::AST::Node]
+
+        body.unshift(enter_render_node(entry.from, entry.file))
+        body.push(leave_render_node(entry.from))
+
+        [enter_node(entry.from), node, leave_node(entry.from)]
+      end
+
+      #: (Herb::AST::Node) -> Array[Herb::AST::Node]
+      def rewrite_node(node)
+        entry = origin.of(node)
+
+        return rewrite_import(node, entry) if entry
+
+        instrument(node)
+
+        if framed?(node)
+          [enter_node(node), node, leave_node(node)]
+        elsif erb_outputs?(node)
+          [replacing(node, wrapped_output(node))]
+        elsif erb_statement?(node)
+          [replacing(node, wrapped_statement(node))]
+        else
+          [node]
+        end
+      end
+
+      #: (Herb::AST::Node, Herb::AST::Node) -> Herb::AST::Node
+      def replacing(node, replacement)
+        context.replacements.record(node, replacement)
+
+        replacement
+      end
+
+      def framed?(node)
+        return true if node.is_a?(Herb::AST::ERBRenderNode)
+
+        block?(node) || (erb_outputs?(node) && assignment?(node))
+      end
+
+      def assignment?(node)
+        return false unless node.respond_to?(:parsed_prism_node)
+        return false unless defined?(::Prism)
+
+        parsed = node.parsed_prism_node
+
+        return false unless parsed
+
+        ASSIGNMENT_NODES.any? { |name| ::Prism.const_defined?(name) && parsed.is_a?(::Prism.const_get(name)) }
+      rescue StandardError
+        false
+      end
+
+      def block?(node)
+        return false unless node.respond_to?(:end_node)
+
+        !node.end_node.nil?
+      end
+
+      def via(node)
+        return nil unless node.is_a?(Herb::AST::ERBRenderNode)
+        return :layout if node.layout_name
+        return :template if node.template_name
+        return :collection if node.keywords&.collection
+        return nil if node.keywords&.object
+
+        :partial
+      end
+
+      def wrapped_output(node)
+        body = code(node)
+        call = captured?(node) ? "output" : "at"
+
+        return erb_node(node, "<%=", "#{SESSION}.#{call}(#{position(node)}) {\n#{body}\n}") if spans_lines?(body)
+
+        erb_node(node, "<%=", "#{SESSION}.#{call}(#{position(node)}) { #{body} }")
+      end
+
+      def captured?(node)
+        return false if !@capture_everything && @capture_output.empty?
+
+        source = code(node)
+
+        return false if source.empty?
+        return true if @capture_everything
+
+        @capture_output.any? do |matcher|
+          matcher.is_a?(Regexp) ? matcher.match?(source) : matcher.call(source)
+        end
+      rescue StandardError
+        false
+      end
+
+      def wrapped_statement(node)
+        body = code(node)
+
+        if spans_lines?(body)
+          return erb_node(node, "<%", "#{SESSION}.enter(#{position(node)}); begin\n#{body}\nensure; #{SESSION}.leave; end")
+        end
+
+        erb_node(node, "<%", "#{SESSION}.enter(#{position(node)}); begin; #{body}; ensure; #{SESSION}.leave; end")
+      end
+
+      #: (String) -> bool
+      def spans_lines?(code)
+        code.include?("\n") || Herb::Engine::Helpers.heredoc?(code) || Herb::Engine::Helpers.comment?(code)
+      end
+
+      def enter_node(node)
+        erb_node(node, "<%", "#{SESSION}.enter(#{position(node)})")
+      end
+
+      def leave_node(node)
+        erb_node(node, "<%", "#{SESSION}.leave")
+      end
+
+      def enter_render_node(node, file)
+        erb_node(node, "<%", "#{SESSION}.enter_render(#{render_arguments(file)}); begin")
+      end
+
+      def render_arguments(file)
+        digest = digest_for(file)
+
+        digest ? "#{file.dump}, #{digest.dump}" : file.dump
+      end
+
+      def digest_for(file)
+        Herb::Fingerprint.template_file(context.project_path + file)
+      rescue StandardError
+        nil
+      end
+
+      def leave_render_node(node)
+        erb_node(node, "<%", "ensure; #{SESSION}.leave_render; end")
+      end
+
+      def position(node)
+        location = node.location
+        parts = [@file.dump, location.start.line, location.start.column, via(node).inspect]
+
+        parts << "end_line: #{location.end.line}"
+        parts << "end_column: #{location.end.column}"
+
+        parts.join(", ")
+      end
+
+      def code(node)
+        return "" unless node.respond_to?(:content)
+
+        node.content&.value.to_s.strip
+      end
+
+      def erb_node(node, opening, code)
+        Herb::AST::ERBContentNode.build(
+          tag_opening: Herb::Token.from("TOKEN_ERB_START", opening),
+          content: Herb::Token.from("TOKEN_ERB_CONTENT", " #{code} "),
+          tag_closing: Herb::Token.from("TOKEN_ERB_END", "%>"),
+          valid: true,
+          location: node.location
+        )
+      end
+    end
+  end
+end