herb 0.10.4 → 0.11.0

data/lib/herb/engine.rb

@@ -5,31 +5,57 @@ require "json"
 require "time"
 require "pathname"
 
-require_relative "engine/debug_visitor"
+require_relative "visitor/context"
+require_relative "visitor/stack"
+require_relative "engine/runtime/session"
+require_relative "visitor/context_aware"
+require_relative "visitor/diagnostics"
+require_relative "engine/helpers"
 require_relative "engine/compiler"
-require_relative "engine/error_formatter"
-require_relative "engine/validation_errors"
-require_relative "engine/parser_error_overlay"
-require_relative "engine/validation_error_overlay"
-require_relative "engine/validators/security_validator"
-require_relative "engine/validators/nesting_validator"
-require_relative "engine/validators/accessibility_validator"
-require_relative "engine/validators/render_validator"
+require_relative "engine/errors"
+require_relative "diagnostic/formatter"
 
 module Herb
   class Engine
-    attr_reader :src, :filename, :project_path, :relative_file_path, :bufvar, :debug, :content_for_head,
-                :validation_error_template, :visitors, :enabled_validators
+    attr_reader :src #: String
+    attr_reader :context #: Visitor::Context
+    attr_reader :bufvar #: String
+    attr_reader :visitors #: Visitor::Stack
 
-    # @rbs!
-    #   def self.optimize_warning_issued: () -> bool
-    #   def self.optimize_warning_issued=: (bool) -> bool
+    #: () -> Pathname?
+    def filename
+      @context.file_path
+    end
+
+    #: () -> Pathname
+    def project_path
+      @context.project_path
+    end
 
-    class << self
-      attr_accessor :optimize_warning_issued #: bool
+    #: () -> String
+    def relative_file_path
+      @context.relative_file_path
     end
 
-    self.optimize_warning_issued = false
+    #: (String) -> String
+    def string_literal(text)
+      "'#{text.gsub(/['\\]/, '\\\\\&')}#{@text_end}"
+    end
+
+    STRING_LITERAL_ESCAPES = {
+      "\\" => "\\\\",
+      '"' => "\\\"",
+      "#" => "\\#",
+      "\n" => "\\n",
+      "\r" => "\\r",
+    }.freeze #: Hash[String, String]
+
+    #: (String) -> String
+    def escaped_string_literal(text)
+      escaped = text.gsub(/[\\"#\n\r]/, STRING_LITERAL_ESCAPES)
+
+      "\"#{escaped}\"#{".freeze" if @freeze_template_literals}"
+    end
 
     ESCAPE_TABLE = {
       "&" => "&amp;",
@@ -39,32 +65,20 @@ module Herb
       "'" => "&#39;",
     }.freeze
 
-    class CompilationError < SyntaxError
-    end
-
-    class GeneratorTemplateError < CompilationError
-    end
-
-    class InvalidRubyError < CompilationError
-      attr_reader :compiled_source
-
-      def initialize(message, compiled_source: nil)
-        @compiled_source = compiled_source
-
-        super(message)
-      end
-    end
+    ATTRIBUTE_ESCAPE_TABLE = ESCAPE_TABLE.merge(
+      "\n" => "&#10;",
+      "\r" => "&#13;",
+      "\t" => "&#9;"
+    ).freeze
 
     def initialize(input, properties = {})
-      @filename = properties[:filename] ? ::Pathname.new(properties[:filename]) : nil
-      @project_path = ::Pathname.new(properties[:project_path] || Dir.pwd)
-
-      if @filename
-        absolute_filename = @filename.absolute? ? @filename : @project_path + @filename
-        @relative_file_path = absolute_filename.relative_path_from(@project_path).to_s
-      else
-        @relative_file_path = "unknown"
-      end
+      @context = Visitor::Context.new(
+        file_path: properties[:filename],
+        project_path: properties[:project_path],
+        options: context_options(properties),
+        resolver: properties[:resolver],
+        **(properties[:context] || {})
+      )
 
       @bufvar = properties[:bufvar] || properties[:outvar] || "_buf"
       @escape = properties.fetch(:escape) { properties.fetch(:escape_html, false) }
@@ -72,38 +86,14 @@ module Herb
       @attrfunc = properties.fetch(:attrfunc, @escape ? "__herb.attr" : "::Herb::Engine.attr")
       @jsfunc = properties.fetch(:jsfunc, @escape ? "__herb.js" : "::Herb::Engine.js")
       @cssfunc = properties.fetch(:cssfunc, @escape ? "__herb.css" : "::Herb::Engine.css")
-      @src = properties[:src] || String.new
+      @src = properties[:src] || +""
       @chain_appends = properties[:chain_appends]
       @buffer_on_stack = false
-      @debug = properties.fetch(:debug, Herb.configuration.engine_option("debug", false))
-      @content_for_head = properties[:content_for_head]
-      @validation_error_template = nil
-      @validation_mode = properties.fetch(:validation_mode, :raise)
-      @enabled_validators = Herb.configuration.enabled_validators(properties[:validators] || {})
-      @optimize = properties.fetch(:optimize, Herb.configuration.engine_option("optimize", false))
       @parser_options = properties.fetch(:parser_options, default_parser_options).transform_keys(&:to_sym)
 
-      if @optimize && !self.class.optimize_warning_issued
-        self.class.optimize_warning_issued = true
-
-        warn "[Herb] Compile-time optimizations are experimental. Output may differ from standard ActionView rendering."
-      end
-
-      @visitors = properties.fetch(:visitors, default_visitors)
-
-      if @debug && @visitors.empty?
-        debug_visitor = DebugVisitor.new(
-          file_path: @filename,
-          project_path: @project_path
-        )
-
-        @visitors << debug_visitor
-      end
-
-      unless [:raise, :overlay, :none].include?(@validation_mode)
-        raise ArgumentError,
-              "validation_mode must be one of :raise, :overlay, or :none, got #{@validation_mode.inspect}"
-      end
+      @visitors = Visitor::Stack.build(properties.fetch(:visitors, Visitor::Stack.new))
+      @visitors.validate_order!
+      @parser_options = Herb::Visitor.parser_options_for(@visitors, @parser_options)
 
       @freeze = properties[:freeze]
       @freeze_template_literals = properties.fetch(:freeze_template_literals, true)
@@ -112,69 +102,54 @@ module Herb
       bufval = properties[:bufval] || "::String.new"
       preamble = properties[:preamble] || "#{@bufvar} = #{bufval};"
       postamble = properties[:postamble] || "#{@bufvar}.to_s\n"
-
       preamble = "#{preamble}; " unless preamble.empty? || preamble.end_with?(";", " ", "\n")
 
       @src << "# frozen_string_literal: true\n" if @freeze
 
-      if properties[:ensure]
-        @src << "begin; __original_outvar = #{@bufvar}"
-        @src << if /\A@[^@]/ =~ @bufvar
-                  "; "
-                else
-                  " if defined?(#{@bufvar}); "
-                end
-      end
-
-      @src << "__herb = ::Herb::Engine; " if @escape && @escapefunc == "__herb.h"
-      @src << preamble
-
-      action_view_helpers = @optimize && source_may_contain_action_view_helpers?(input)
-      transform_conditionals = @optimize && action_view_helpers
-      parse_result = ::Herb.parse(input, **@parser_options, track_whitespace: true,
-                                                            action_view_helpers: action_view_helpers,
-                                                            transform_conditionals: transform_conditionals)
-      ast = parse_result.value
+      parse_result = ::Herb.parse(input, **parse_options, track_whitespace: true)
       parser_errors = parse_result.errors
 
       if parser_errors.any?
-        case @validation_mode
-        when :raise
-          handle_parser_errors(parser_errors, input, ast)
-          return
-        when :overlay
-          add_parser_error_overlay(parser_errors, input)
-        when :none
-          # Skip both errors and compilation, but still need minimal Ruby code
-        end
+        handle_parser_errors(parser_errors, input, parse_result.value)
       else
-        validators = run_validation(ast) unless @validation_mode == :none
+        @visitors.each do |visitor|
+          visitor.inherit_context(@context) if visitor.is_a?(Visitor::ContextAware)
+          visitor.bufvar = @bufvar if visitor.respond_to?(:bufvar=)
 
-        if validators
-          handle_validation_errors(validators, input) if @validation_mode == :raise
-          add_validation_overlay(validators, input) if @validation_mode == :overlay
+          parse_result.value.accept(visitor)
         end
 
-        @visitors.each do |visitor|
-          ast.accept(visitor)
+        @visitors.each do |visitor| # rubocop:disable Style/CombinableLoops
+          visitor.finish(parse_result.value) if visitor.respond_to?(:finish)
         end
 
-        compiler = Compiler.new(self, properties)
+        wrapping = wrap_postamble(postamble)
+        wrapped = !wrapping.equal?(postamble)
+        postamble = wrapping
 
-        ast.accept(compiler)
+        compiler = compiler_class.new(self, properties.merge(source: input))
 
-        compiler.generate_output
-      end
+        parse_result.value.accept(compiler)
 
-      if @validation_error_template
-        escaped_html = @validation_error_template.gsub("'", "\\\\'")
-        @src << " #{@bufvar} << ('#{escaped_html}'.html_safe).to_s;"
-      end
+        static_body = buffer_required?(properties) || wrapped ? nil : compile_static_body(compiler)
+
+        if static_body
+          @src << static_body
+        else
+          write_buffer_prelude(properties, preamble)
+
+          report(input)
+
+          compiler.generate_output
 
-      @src << "\n" unless @src.end_with?("\n")
-      add_postamble(postamble)
+          @src << "\n" unless @src.end_with?("\n")
+          add_postamble(postamble)
 
-      @src << "; ensure\n  #{@bufvar} = __original_outvar\nend\n" if properties[:ensure]
+          @src << "; ensure\n  #{@bufvar} = __original_outvar\nend\n" if properties[:ensure]
+
+          insert_herb_alias!
+        end
+      end
 
       if properties.fetch(:validate_ruby, false)
         ensure_valid_ruby!(@src)
@@ -188,16 +163,15 @@ module Herb
       value.to_s.gsub(/[&<>"']/, ESCAPE_TABLE)
     end
 
+    #: (untyped) -> String
+    def self.raw(value)
+      string = value.to_s
+
+      string.respond_to?(:html_safe) ? string.html_safe : string
+    end
+
     def self.attr(value)
-      value.to_s
-           .gsub("&", "&amp;")
-           .gsub('"', "&quot;")
-           .gsub("'", "&#39;")
-           .gsub("<", "&lt;")
-           .gsub(">", "&gt;")
-           .gsub("\n", "&#10;")
-           .gsub("\r", "&#13;")
-           .gsub("\t", "&#9;")
+      value.to_s.gsub(/[&<>"'\n\r\t]/, ATTRIBUTE_ESCAPE_TABLE)
     end
 
     def self.js(value)
@@ -224,36 +198,13 @@ module Herb
       value.is_a?(::String) || value.is_a?(::Symbol) ? value.to_s : value.to_json
     end
 
-    def self.comment?(code)
-      code.include?("#")
-    end
-
-    def self.heredoc?(code)
-      code.match?(/<<[~-]?\s*['"`]?\w/)
-    end
-
-    def source_may_contain_action_view_helpers?(source)
-      self.class.action_view_helper_pattern.match?(source)
-    end
-
-    def self.action_view_helper_pattern
-      @action_view_helper_pattern ||= begin
-        require_relative "action_view/helper_registry"
-
-        names = ::Herb::ActionView::HelperRegistry.supported.flat_map { |entry|
-          if entry.receiver_call_detect?
-            "#{entry.name}."
-          else
-            [entry.name, *entry.aliases]
-          end
-        }
+    protected
 
-        Regexp.new("\\b(?:#{names.map { |name| Regexp.escape(name) }.join("|")})")
-      end
+    #: () -> untyped
+    def compiler_class
+      Compiler
     end
 
-    protected
-
     def add_text(text)
       return if text.empty?
 
@@ -266,14 +217,15 @@ module Herb
       terminate_expression
 
       if code.include?("=begin") || code.include?("=end")
-        @src << "\n" << code << "\n"
+        @src << "\n" << code
+        @src << "\n" unless code.end_with?("\n")
       else
         @src.chomp! if @src.end_with?("\n") && code.start_with?(" ") && !code.end_with?("\n")
 
-        @src << " " << code
+        @src << " " unless code.match?(/\A\n+\z/)
+        @src << code
 
-        # TODO: rework and check for Prism::InlineComment as soon as we expose the Prism Nodes in the Herb AST
-        if self.class.comment?(code) || self.class.heredoc?(code)
+        if Helpers.comment?(code) || Helpers.heredoc?(code)
           @src << "\n" unless code[-1] == "\n"
         else
           @src << ";" unless code[-1] == "\n"
@@ -359,10 +311,10 @@ module Herb
         trailing_newline = code.end_with?("\n")
         code_stripped = code.chomp
 
-        @src.chomp! if @src.end_with?("\n") && code_stripped.start_with?(" ")
+        @src.chomp! if @src.end_with?("\n") && code_stripped.start_with?(" ") && !trailing_newline
 
         @src << " " << code_stripped
-        @src << "\n" if self.class.comment?(code_stripped)
+        @src << "\n" if Helpers.comment?(code_stripped)
         @src << (escaped ? "))" : ")")
         @src << (trailing_newline ? "\n" : ";")
 
@@ -373,8 +325,8 @@ module Herb
     end
 
     def trailing_newline(code)
-      return "\n" if self.class.comment?(code)
-      return "\n" if self.class.heredoc?(code)
+      return "\n" if Helpers.comment?(code)
+      return "\n" if Helpers.ends_on_heredoc_terminator?(code)
 
       ""
     end
@@ -402,121 +354,130 @@ module Herb
 
     private
 
-    def run_validation(ast)
-      validators = [
-        Validators::SecurityValidator.new(enabled: @enabled_validators[:security]),
-        Validators::NestingValidator.new(enabled: @enabled_validators[:nesting]),
-        Validators::AccessibilityValidator.new(enabled: @enabled_validators[:accessibility])
-      ]
+    #: (Hash[Symbol, untyped]) -> bool
+    def buffer_required?(properties)
+      return true if properties[:ensure] || properties[:preamble] || properties[:postamble] || properties[:bufval]
+
+      collected_diagnostics.any?
+    end
+
+    #: (String) -> String
+    def wrap_postamble(postamble)
+      @visitors.reduce(postamble) do |carried, visitor|
+        visitor.respond_to?(:postamble) ? visitor.postamble(carried) : carried
+      end
+    end
+
+    #: (untyped) -> String?
+    def compile_static_body(compiler)
+      @visitors.each do |visitor|
+        next unless visitor.respond_to?(:compile_static_body)
+
+        body = visitor.compile_static_body(self, compiler)
 
-      validators.select(&:enabled?).each do |validator|
-        ast.accept(validator)
+        return body if body
       end
 
-      validators
+      nil
     end
 
-    def handle_parser_errors(parser_errors, input, _ast)
-      case @validation_mode
-      when :raise
-        formatter = ErrorFormatter.new(input, parser_errors, filename: @filename)
-        message = formatter.format_all
-
-        raise CompilationError, "\n#{message}"
-      when :overlay
-        add_parser_error_overlay(parser_errors, input)
-        @src << "\n" unless @src.end_with?("\n")
-        add_postamble("#{@bufvar}.to_s\n")
-      when :none
-        @src << "\n" unless @src.end_with?("\n")
-        add_postamble("#{@bufvar}.to_s\n")
+    #: () -> Array[Herb::Diagnostic]
+    def collected_diagnostics
+      @visitors.grep(Visitor::Diagnostics).flat_map(&:diagnostics)
+    end
+
+    #: (Hash[Symbol, untyped], String) -> void
+    def write_buffer_prelude(properties, preamble)
+      if properties[:ensure]
+        @src << "begin; __original_outvar = #{@bufvar}"
+        @src << (/\A@[^@]/.match?(@bufvar) ? "; " : " if defined?(#{@bufvar}); ")
       end
+
+      @herb_alias_index = (@src.length if @escape && @escapefunc == "__herb.h")
+      @src << preamble
+    end
+
+    #: () -> void
+    def insert_herb_alias!
+      return unless @herb_alias_index
+      return unless @src.include?("__herb.")
+
+      @src.insert(@herb_alias_index, "__herb = ::Herb::Engine; ")
+    end
+
+    def handle_parser_errors(parser_errors, input, _ast)
+      diagnostics = Diagnostic.from_errors(parser_errors, template: relative_file_path)
+      formatter = Diagnostic::Formatter.new(input, diagnostics, filename: filename)
+
+      raise ParseError.new(
+        formatter.summary,
+        details: formatter,
+        diagnostics: diagnostics,
+        source: input,
+        filename: relative_file_path,
+        visitors: @visitors.descriptions,
+        parser_options: @parser_options
+      )
+    end
+
+    #: (String) -> void
+    def report(input)
+      reporters = @visitors.grep(Visitor::Diagnostics)
+      diagnostics = reporters.flat_map(&:diagnostics)
+
+      return if diagnostics.empty?
+
+      emit_compile_diagnostics(diagnostics)
+
+      fatal = reporters.select { |reporter| reporter.respond_to?(:fatal?) && reporter.fatal? }
+
+      raise_for(fatal.flat_map(&:errors), input)
+    end
+
+    #: (Array[Herb::Diagnostic]) -> void
+    def emit_compile_diagnostics(diagnostics)
+      entries = diagnostics.map { |diagnostic| diagnostic.to_ruby(relative_file_path) }.join(", ")
+
+      @src << " ::Herb::Engine::Runtime::Session.record_compile_diagnostics(#{relative_file_path.inspect}, [#{entries}].freeze);"
     end
 
-    def handle_validation_errors(validators, input)
-      errors = validators.select(&:enabled?).flat_map(&:errors)
-      return unless errors.any?
+    #: (Array[Herb::Diagnostic], String) -> void
+    def raise_for(errors, input)
+      return if errors.empty?
 
-      security_error = errors.find { |error| error[:source] == "SecurityValidator" }
+      declared = errors.find(&:error_class)
+      error_class = declared&.error_class
 
-      if security_error
-        raise SecurityError.new(
-          security_error[:message],
-          line: security_error[:location]&.start&.line,
-          column: security_error[:location]&.start&.column,
-          filename: @filename,
-          suggestion: security_error[:suggestion]
+      if declared && error_class
+        raise error_class.new(
+          declared.message,
+          line: declared.location&.start&.line,
+          column: declared.location&.start&.column,
+          filename: filename,
+          suggestion: declared.suggestion
         )
       end
 
-      formatter = ErrorFormatter.new(input, errors, filename: @filename)
-      message = formatter.format_all
-      raise CompilationError, "\n#{message}"
-    end
-
-    def add_validation_overlay(validators, input = nil)
-      errors = validators.select(&:enabled?).flat_map(&:errors)
-      return unless errors.any?
-
-      templates = errors.map { |error|
-        location = error[:location]
-        line = location&.start&.line || 0
-        column = location&.start&.column || 0
-
-        source = input || @src
-        overlay_generator = ValidationErrorOverlay.new(source, error, filename: @relative_file_path)
-        html_fragment = overlay_generator.generate_fragment
-
-        escaped_message = escape_attr(error[:message])
-        escaped_suggestion = error[:suggestion] ? escape_attr(error[:suggestion]) : ""
-
-        <<~TEMPLATE
-          <template
-            data-herb-validation-error
-            data-severity="#{error[:severity]}"
-            data-source="#{error[:source]}"
-            data-code="#{error[:code]}"
-            data-line="#{line}"
-            data-column="#{column}"
-            data-filename="#{escape_attr(@relative_file_path)}"
-            data-message="#{escaped_message}"
-            #{"data-suggestion=\"#{escaped_suggestion}\"" if error[:suggestion]}
-            data-timestamp="#{Time.now.utc.iso8601}"
-          >#{html_fragment}</template>
-        TEMPLATE
-      }.join
-
-      @validation_error_template = templates
-    end
-
-    def escape_attr(text)
-      text.to_s
-          .gsub("&", "&amp;")
-          .gsub('"', "&quot;")
-          .gsub("'", "&#39;")
-          .gsub("<", "&lt;")
-          .gsub(">", "&gt;")
-          .gsub("\n", "&#10;")
-          .gsub("\r", "&#13;")
-          .gsub("\t", "&#9;")
-    end
-
-    def add_parser_error_overlay(parser_errors, input)
-      return unless parser_errors.any?
-
-      overlay_generator = ParserErrorOverlay.new(
-        input,
-        parser_errors,
-        filename: @relative_file_path
+      formatter = Diagnostic::Formatter.new(input, errors, filename: filename)
+
+      raise CompilationError.new(
+        formatter.summary,
+        details: formatter,
+        diagnostics: errors,
+        visitors: @visitors.descriptions,
+        parser_options: @parser_options
       )
+    end
 
-      error_html = overlay_generator.generate_html
-      @validation_error_template = "<template data-herb-parser-error>#{error_html}</template>"
+    def context_options(properties)
+      properties.except(:visitors, :src, :context, :resolver)
     end
 
-    #: () -> Array[Herb::Visitor]
-    def default_visitors
-      []
+    #: () -> Hash[Symbol, untyped]
+    def parse_options
+      return @parser_options if @parser_options.key?(:track_locations)
+
+      @parser_options.merge(track_locations: false)
     end
 
     #: () -> Hash[Symbol, untyped]
@@ -543,7 +504,7 @@ module Herb
       syntax_errors = prism_result.errors.reject { |error| error.type == :invalid_yield }
 
       if syntax_errors.any?
-        details = syntax_errors.map { |err| "  - #{err.message} (line #{err.location.start_line})" }.join("\n")
+        details = syntax_errors.map { |error| "  - #{error.message} (line #{error.location.start_line})" }.join("\n")
         raise InvalidRubyError.new("Compiled template produced invalid Ruby:\n#{details}", compiled_source: @src)
       end
     end

data/lib/herb/ensure_installed.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Herb
+  #: (*String gems) -> void
+  def self.ensure_installed(*gems)
+    missing = gems.reject do |name|
+      require name
+      true
+    rescue LoadError
+      false
+    end
+
+    return if missing.empty?
+
+    refuse_bundle_replacement(missing) if defined?(Bundler) && Bundler.instance_variable_get(:@definition) && !@inline_gemfile
+
+    @inline_gemfile = true
+
+    require "bundler/inline"
+
+    verbose = $VERBOSE
+    $VERBOSE = nil
+
+    begin
+      gemfile(true, quiet: true) do # steep:ignore
+        source "https://rubygems.org" # steep:ignore
+        missing.each { |name| gem name }
+      end
+    ensure
+      $VERBOSE = verbose
+    end
+  end
+
+  #: (Array[String]) -> void
+  def self.refuse_bundle_replacement(missing)
+    names = missing.map { |name| "`#{name}`" }.join(", ")
+    additions = missing.map { |name| "`gem \"#{name}\"`" }.join(", ")
+
+    raise LoadError, "Herb needs the #{names} #{missing.one? ? "gem" : "gems"}. Add #{additions} to the Gemfile."
+  end
+
+  private_class_method :refuse_bundle_replacement
+end