herb 0.10.4 → 0.11.0

data/lib/herb/engine/{debug_visitor.rb → visitors/debug_visitor.rb}

@@ -1,32 +1,37 @@
 # frozen_string_literal: true
 # typed: false
 
+require_relative "../../visitor"
+require_relative "../../visitor/context_aware"
+
 module Herb
   class Engine
     class DebugVisitor < Herb::Visitor
-      def initialize(file_path: nil, project_path: nil)
+      include Herb::Visitor::ContextAware
+
+      required_parser_option track_locations: true
+
+      #: () -> bool
+      def self.reads_erb_source?
+        true
+      end
+
+      # `node` adds the render occurrence to every marker, which needs `InstrumentationVisitor` in the
+      # same stack to have anything to report. Without it the value is empty on every tag, so it is
+      # asked for rather than assumed.
+      #
+      #     Herb::Engine.new(source, visitors: [
+      #       Herb::Engine::DebugVisitor.new(node: true),
+      #       Herb::Engine::InstrumentationVisitor.new
+      #     ])
+      #
+      def initialize(node: false)
         super()
 
-        @filename = case file_path
-                    when ::Pathname
-                      file_path
-                    when String
-                      file_path.empty? ? nil : ::Pathname.new(file_path)
-                    end
-
-        @project_path = case project_path
-                        when ::Pathname
-                          project_path
-                        when String
-                          ::Pathname.new(project_path)
-                        else
-                          ::Pathname.new(Dir.pwd)
-                        end
-
-        @relative_file_path = calculate_relative_path
+        @node = node
         @top_level_elements = [] #: Array[Herb::AST::HTMLElementNode]
         @element_stack = [] #: Array[String]
-        @erb_block_stack = [] #: Array[Herb::AST::ERBBlockNode]
+        @erb_block_stack = [] #: Array[(Herb::AST::ERBBlockNode | Herb::AST::ERBIterationBlockNode)]
         @debug_attributes_applied = false
         @in_attribute = false
         @in_html_comment = false
@@ -92,34 +97,30 @@ module Herb
         @erb_block_stack.pop
       end
 
-      private
+      def visit_erb_iteration_block_node(node)
+        @erb_block_stack.push(node)
+        super
+        @erb_block_stack.pop
+      end
 
-      def calculate_relative_path
-        return "unknown" unless @filename
+      def inspect
+        return "#<#{self.class.name}>" unless @node
 
-        if @filename.absolute?
-          @filename.relative_path_from(@project_path).to_s
-        else
-          @filename.to_s
-        end
-      rescue ArgumentError
-        @filename.to_s
+        "#<#{self.class.name} node=true>"
       end
 
-      def wrap_all_erb_nodes(node)
-        replace_erb_nodes_recursive(node)
+      private
+
+      def filename
+        context.file_path
       end
 
-      # Creates a dummy location for AST nodes that don't need real location info
-      #: () -> Herb::Location
-      def dummy_location
-        @dummy_location ||= Herb::Location.from(0, 0, 0, 0)
+      def relative_file_path
+        context.relative_file_path
       end
 
-      # Creates a dummy range for tokens that don't need real range info
-      #: () -> Herb::Range
-      def dummy_range
-        @dummy_range ||= Herb::Range.from(0, 0)
+      def wrap_all_erb_nodes(node)
+        replace_erb_nodes_recursive(node)
       end
 
       def replace_erb_nodes_recursive(node)
@@ -179,10 +180,12 @@ module Herb
         debug_attributes = [
           create_debug_attribute("data-herb-debug-outline-type", view_type),
           create_debug_attribute("data-herb-debug-file-name", component_display_name),
-          create_debug_attribute("data-herb-debug-file-relative-path", @relative_file_path || "unknown"),
-          create_debug_attribute("data-herb-debug-file-full-path", @filename&.to_s || "unknown")
+          create_debug_attribute("data-herb-debug-file-relative-path", relative_file_path),
+          create_debug_attribute("data-herb-debug-file-full-path", filename&.to_s || "unknown")
         ]
 
+        debug_attributes << create_debug_node_attribute if @node
+
         if @top_level_elements.length > 1
           debug_attributes << create_debug_attribute("data-herb-debug-attach-to-parent", "true")
         end
@@ -192,21 +195,50 @@ module Herb
         @debug_attributes_applied = true
       end
 
-      def create_debug_attribute(name, value)
-        name_literal = Herb::AST::LiteralNode.new("LiteralNode", dummy_location, [], name.dup)
-        name_node = Herb::AST::HTMLAttributeNameNode.new("HTMLAttributeNameNode", dummy_location, [], [name_literal])
+      def create_debug_node_attribute
+        name_literal = Herb::AST::LiteralNode.build(content: +"data-herb-debug-node")
+        name_node = Herb::AST::HTMLAttributeNameNode.build(children: [name_literal])
 
-        value_literal = Herb::AST::LiteralNode.new("LiteralNode", dummy_location, [], value.dup)
-        value_node = Herb::AST::HTMLAttributeValueNode.new("HTMLAttributeValueNode", dummy_location, [], create_token(:quote, '"'),
-                                                           [value_literal], create_token(:quote, '"'), true)
+        value_node = Herb::AST::HTMLAttributeValueNode.build(
+          open_quote: Herb::Token.from(:quote, '"'),
+          children: [current_node_erb],
+          close_quote: Herb::Token.from(:quote, '"'),
+          quoted: true
+        )
 
-        equals_token = create_token(:equals, "=")
+        Herb::AST::HTMLAttributeNode.build(
+          name: name_node,
+          equals: Herb::Token.from(:equals, "="),
+          value: value_node
+        )
+      end
 
-        Herb::AST::HTMLAttributeNode.new("HTMLAttributeNode", dummy_location, [], name_node, equals_token, value_node)
+      def current_node_erb
+        Herb::AST::ERBContentNode.build(
+          tag_opening: Herb::Token.from("TOKEN_ERB_START", "<%="),
+          content: Herb::Token.from("TOKEN_ERB_CONTENT", " ::Herb::Engine::Runtime::Session.current_node "),
+          tag_closing: Herb::Token.from("TOKEN_ERB_END", "%>"),
+          valid: true
+        )
       end
 
-      def create_token(type, value)
-        Herb::Token.new(value.dup, dummy_range, dummy_location, type.to_s)
+      def create_debug_attribute(name, value)
+        name_literal = Herb::AST::LiteralNode.build(content: name.dup)
+        name_node = Herb::AST::HTMLAttributeNameNode.build(children: [name_literal])
+
+        value_literal = Herb::AST::LiteralNode.build(content: value.dup)
+        value_node = Herb::AST::HTMLAttributeValueNode.build(
+          open_quote: Herb::Token.from(:quote, '"'),
+          children: [value_literal],
+          close_quote: Herb::Token.from(:quote, '"'),
+          quoted: true
+        )
+
+        Herb::AST::HTMLAttributeNode.build(
+          name: name_node,
+          equals: Herb::Token.from(:equals, "="),
+          value: value_node
+        )
       end
 
       def create_debug_span_for_erb(erb_node)
@@ -216,11 +248,9 @@ module Herb
 
         return erb_node if complex_rails_helper?(code)
 
-        line = erb_node.location&.start&.line
-        column = erb_node.location&.start&.column
+        position = erb_node.location&.start&.to_one_based
 
-        escaped_erb = erb_code.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;").gsub("'",
-                                                                                                               "&#39;")
+        escaped_erb = Herb::Engine.h(erb_code)
 
         outline_type = if @top_level_elements.empty?
                          "erb-output #{determine_view_type}"
@@ -232,40 +262,42 @@ module Herb
           create_debug_attribute("data-herb-debug-outline-type", outline_type),
           create_debug_attribute("data-herb-debug-erb", escaped_erb),
           create_debug_attribute("data-herb-debug-file-name", component_display_name),
-          create_debug_attribute("data-herb-debug-file-relative-path", @relative_file_path || "unknown"),
-          create_debug_attribute("data-herb-debug-file-full-path", @filename&.to_s || "unknown"),
+          create_debug_attribute("data-herb-debug-file-relative-path", relative_file_path),
+          create_debug_attribute("data-herb-debug-file-full-path", filename&.to_s || "unknown"),
           create_debug_attribute("data-herb-debug-inserted", "true")
         ]
 
-        debug_attributes << create_debug_attribute("data-herb-debug-line", line.to_s) if line
-        debug_attributes << create_debug_attribute("data-herb-debug-column", (column + 1).to_s) if column
+        debug_attributes << create_debug_node_attribute if @node
+
+        if position
+          debug_attributes << create_debug_attribute("data-herb-debug-line", position[:line].to_s)
+          debug_attributes << create_debug_attribute("data-herb-debug-column", position[:column].to_s)
+        end
+
         debug_attributes << create_debug_attribute("style", "display: contents;")
 
-        tag_name_token = create_token(:tag_name, "span")
-
-        open_tag = Herb::AST::HTMLOpenTagNode.new(
-          "HTMLOpenTagNode",
-          dummy_location,
-          [],
-          create_token(:tag_opening, "<"),
-          tag_name_token,
-          create_token(:tag_closing, ">"),
-          debug_attributes,
-          false
+        tag_name_token = Herb::Token.from(:tag_name, "span")
+
+        open_tag = Herb::AST::HTMLOpenTagNode.build(
+          tag_opening: Herb::Token.from(:tag_opening, "<"),
+          tag_name: tag_name_token,
+          tag_closing: Herb::Token.from(:tag_closing, ">"),
+          children: debug_attributes
         )
 
-        close_tag = Herb::AST::HTMLCloseTagNode.new(
-          "HTMLCloseTagNode",
-          dummy_location,
-          [],
-          create_token(:tag_opening, "</"),
-          create_token(:tag_name, "span"),
-          [],
-          create_token(:tag_closing, ">")
+        close_tag = Herb::AST::HTMLCloseTagNode.build(
+          tag_opening: Herb::Token.from(:tag_opening, "</"),
+          tag_name: Herb::Token.from(:tag_name, "span"),
+          tag_closing: Herb::Token.from(:tag_closing, ">")
         )
 
-        Herb::AST::HTMLElementNode.new("HTMLElementNode", dummy_location, [], open_tag, tag_name_token, [erb_node], close_tag,
-                                       false, "Debug")
+        Herb::AST::HTMLElementNode.build(
+          open_tag: open_tag,
+          tag_name: tag_name_token,
+          body: [erb_node],
+          close_tag: close_tag,
+          element_source: "Debug"
+        )
       end
 
       def determine_view_type
@@ -279,30 +311,30 @@ module Herb
       end
 
       def partial?
-        return false unless @filename
+        return false unless filename
 
-        basename = @filename.basename.to_s
+        basename = filename.basename.to_s
         basename.start_with?("_")
       end
 
       def component?
-        return false unless @filename
+        return false unless filename
 
-        @filename.to_s.match?(%r{(^|/)app/components/})
+        filename.to_s.match?(%r{(^|/)app/components/})
       end
 
       def sidecar_component?
         return false unless component?
-        return false unless @filename
+        return false unless filename
 
-        @filename.basename.to_s.match?(/\Acomponent\.(html\.erb|html\.herb|erb|herb)\z/)
+        filename.basename.to_s.match?(/\Acomponent\.(html\.erb|html\.herb|erb|herb)\z/)
       end
 
       def component_display_name
-        return @filename&.basename&.to_s || "unknown" unless @filename
+        return filename&.basename&.to_s || "unknown" unless filename
 
-        basename = @filename.basename.to_s
-        path = @filename.to_s
+        basename = filename.basename.to_s
+        path = filename.to_s
 
         if sidecar_component? && (match = path.match(%r{/components/(.+)/component\.[^/]+\z}))
           return match[1].split("/").map { |s| classify(s) }.join("::")
@@ -346,10 +378,6 @@ module Herb
         false
       end
 
-      def erb_output?(opening)
-        opening.include?("=") && !opening.include?("#")
-      end
-
       # TODO: Rewrite using Prism Nodes once available
       def complex_rails_helper?(code)
         cleaned_code = code.strip.gsub(/\s+/, " ")

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

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+# typed: false
+
+require_relative "../../../herb"
+require_relative "../runtime/html_safe_assertions"
+
+begin
+  require "prism"
+rescue LoadError
+  raise LoadError,
+        "Herb::Engine::HTMLSafeAssertionsVisitor requires the `prism` gem. " \
+        "Add it to your Gemfile or install it with: gem install prism"
+end
+
+module Herb
+  class Engine
+    # Wraps the receiver of every `.html_safe` call in a template with a runtime assertion, so
+    # that marking a value as HTML-safe raises when the value contains HTML that the browser
+    # executes.
+    #
+    # This visitor is not loaded by default. Require it explicitly and pass it to the engine:
+    #
+    #     require "herb/engine/visitors/html_safe_assertions_visitor"
+    #
+    #     Herb::Engine.new(source, visitors: [Herb::Engine::HTMLSafeAssertionsVisitor.new])
+    #
+    # `<%= @user.bio.html_safe %>` then compiles as if the template had been written as:
+    #
+    #     <%= ::Herb::Engine::Runtime::HTMLSafeAssertions.check(@user.bio, file: __FILE__, line: 1, column: 1, source: "<%= @user.bio.html_safe %>", mode: :raise).html_safe %>
+    #
+    # The assertion runs on every render, and the value keeps flowing through `.html_safe`
+    # unchanged. See `Herb::Engine::Runtime::HTMLSafeAssertions` for what counts as unsafe.
+    #
+    # The calls are found in the Prism program the parser attaches to the document, which the
+    # engine enables through `required_parser_option`. Parsing an AST for this visitor by hand
+    # needs the same option:
+    #
+    #     Herb.parse(source, prism_program: true)
+    #
+    class HTMLSafeAssertionsVisitor < Herb::Visitor
+      include Herb::Visitor::ContextAware
+
+      required_parser_option track_locations: true
+
+      RUNTIME = "::Herb::Engine::Runtime::HTMLSafeAssertions"
+
+      MAX_SOURCE_LENGTH = 120
+
+      required_parser_option prism_program: true
+
+      class MissingPrismProgramError < StandardError
+      end
+
+      #: (?mode: Symbol, ?ignore: Array[Symbol], ?file_path: (String | ::Pathname)?) -> void
+      def initialize(mode: :raise, ignore: [], file_path: nil)
+        super()
+
+        @mode = validated_mode(mode)
+        @ignore = validated_ignore(ignore)
+        @erb_nodes = [] #: Array[untyped]
+
+        self.context = Context.new(file_path: file_path) if file_path
+      end
+
+      #: (Herb::AST::DocumentNode) -> void
+      def visit_document_node(node)
+        @erb_nodes = [] #: Array[untyped]
+
+        super
+
+        add_assertions(node)
+      end
+
+      #: (Herb::AST::Node) -> void
+      def visit_erb_node(node)
+        @erb_nodes << node if content_token(node)
+      end
+
+      #: () -> String
+      def inspect
+        "#<#{self.class.name} mode=#{@mode.inspect} ignore=#{@ignore.inspect} file_path=#{context.file_path&.to_s.inspect}>"
+      end
+
+      private
+
+      #: (Symbol) -> Symbol
+      def validated_mode(mode)
+        return mode if Engine::Runtime::HTMLSafeAssertions::MODES.include?(mode)
+
+        raise ArgumentError,
+              "mode must be one of #{Engine::Runtime::HTMLSafeAssertions::MODES.map(&:inspect).join(", ")}, got #{mode.inspect}"
+      end
+
+      #: (Array[Symbol]) -> Array[Symbol]
+      def validated_ignore(ignore)
+        names = ignore.map(&:to_sym)
+        unknown = names - Engine::Runtime::HTMLSafeAssertions::CHECK_NAMES
+
+        return names if unknown.empty?
+
+        raise ArgumentError,
+              "unknown check #{unknown.map(&:inspect).join(", ")}, expected one of #{Engine::Runtime::HTMLSafeAssertions::CHECK_NAMES.map(&:inspect).join(", ")}"
+      end
+
+      #: (Herb::AST::DocumentNode) -> void
+      def add_assertions(document)
+        targets = html_safe_targets(document)
+
+        return if targets.empty?
+
+        @erb_nodes.each { |node| rewrite(node, targets) }
+      end
+
+      #: (Herb::AST::DocumentNode) -> Array[[Symbol, Prism::Location]]
+      def html_safe_targets(document)
+        program = document.deserialized_prism_node
+
+        unless program.is_a?(Prism::ProgramNode)
+          raise MissingPrismProgramError,
+                "#{self.class.name} needs the document to be parsed with the `prism_program` parser option. " \
+                "Pass the visitor to `Herb::Engine`, which enables it, or parse with `Herb.parse(source, prism_program: true)`."
+        end
+
+        targets = [] #: Array[[Symbol, Prism::Location]]
+        queue = [program] #: Array[Prism::Node]
+
+        until queue.empty?
+          current = queue.shift
+
+          queue.concat(current.compact_child_nodes)
+
+          target = target_for(current)
+
+          targets << target if target
+        end
+
+        targets
+      end
+
+      #: (Prism::Node) -> [Symbol, Prism::Location]?
+      def target_for(node)
+        if node.is_a?(Prism::CallNode) && html_safe_call?(node)
+          receiver = node.receiver
+
+          return [:receiver, receiver.location] if receiver
+        end
+
+        if node.is_a?(Prism::BlockArgumentNode) && html_safe_symbol?(node)
+          expression = node.expression
+
+          return [:symbol_to_proc, expression.location] if expression
+        end
+
+        nil
+      end
+
+      #: (Prism::CallNode) -> bool
+      def html_safe_call?(node)
+        return false unless node.name == :html_safe
+        return false unless node.receiver
+        return false if node.arguments || node.block
+
+        true
+      end
+
+      #: (Prism::BlockArgumentNode) -> bool
+      def html_safe_symbol?(node)
+        expression = node.expression
+
+        expression.is_a?(Prism::SymbolNode) && expression.unescaped == "html_safe"
+      end
+
+      #: (untyped, Array[[Symbol, Prism::Location]]) -> void
+      def rewrite(node, targets)
+        token = content_token(node)
+
+        return unless token
+
+        code = token.value
+
+        return unless code.include?("html_safe")
+
+        range = token.range
+
+        return unless range
+        return unless range.to - range.from == code.bytesize
+
+        local = targets.filter_map { |kind, location| local_target(kind, location, range) }
+
+        return if local.empty?
+
+        arguments = check_arguments(node, code)
+        rewritten = code
+
+        edits(local, arguments).each do |start_offset, end_offset, text|
+          rewritten = splice(rewritten, start_offset, end_offset, text)
+        end
+
+        token.value.replace(rewritten)
+      end
+
+      #: (Symbol, Prism::Location, Herb::Range) -> [Symbol, Integer, Integer]?
+      def local_target(kind, location, range)
+        return nil unless location.start_offset >= range.from
+        return nil unless location.end_offset <= range.to
+
+        [kind, location.start_offset - range.from, location.end_offset - range.from]
+      end
+
+      #: (Array[[Symbol, Integer, Integer]], String) -> Array[[Integer, Integer, String]]
+      def edits(targets, arguments)
+        edits = [] #: Array[[Integer, Integer, String]]
+
+        targets.each do |kind, start_offset, end_offset|
+          if kind == :symbol_to_proc
+            edits << [start_offset, end_offset, "->(value, *rest) { #{RUNTIME}.check(value#{arguments}).html_safe(*rest) }"]
+
+            next
+          end
+
+          edits << [end_offset, end_offset, "#{arguments})"]
+          edits << [start_offset, start_offset, "#{RUNTIME}.check("]
+        end
+
+        edits.sort_by { |start_offset, _end_offset, _text| -start_offset }
+      end
+
+      #: (String, Integer, Integer, String) -> String
+      def splice(string, start_offset, end_offset, text)
+        "#{string.byteslice(0, start_offset)}#{text}#{string.byteslice(end_offset..-1)}"
+      end
+
+      #: (untyped) -> Herb::Token?
+      def content_token(node)
+        token = node.respond_to?(:content) ? node.content : nil
+
+        token.is_a?(Herb::Token) ? token : nil
+      end
+
+      #: (untyped, String) -> String
+      def check_arguments(node, code)
+        parts = ["file: #{file_argument}"] #: Array[String]
+
+        location = node.location
+
+        if location
+          position = location.start.to_one_based
+
+          parts << "line: #{position[:line]}"
+          parts << "column: #{position[:column]}"
+        end
+
+        parts << "source: #{erb_source(node, code).dump}.freeze"
+        parts << "mode: #{@mode.inspect}"
+        parts << "ignore: #{@ignore.inspect}.freeze" if @ignore.any?
+
+        ", #{parts.join(", ")}"
+      end
+
+      #: () -> String
+      def file_argument
+        return "__FILE__" unless context.file_path
+
+        "#{context.relative_file_path.dump}.freeze"
+      end
+
+      #: (untyped, String) -> String
+      def erb_source(node, code)
+        opening = node.respond_to?(:tag_opening) ? node.tag_opening&.value : nil
+        closing = node.respond_to?(:tag_closing) ? node.tag_closing&.value : nil
+
+        truncate("#{opening}#{code}#{closing}")
+      end
+
+      #: (String) -> String
+      def truncate(string)
+        string.length > MAX_SOURCE_LENGTH ? "#{string[0, MAX_SOURCE_LENGTH]}..." : string
+      end
+    end
+  end
+end