mjml-rb 0.5.1 → 0.6.0

data/lib/mjml-rb/formatter.rb

@@ -0,0 +1,113 @@
+module MjmlRb
+  # A deliberately conservative formatter: tokenize markup before changing
+  # whitespace, and never reserialize the document (which can damage VML/MSO).
+  class Formatter
+    IGNORE = /<!--\s*htmlmin:ignore\s*-->/
+    PROTECTED = /<!--\s*htmlmin:ignore\s*-->.*?<!--\s*htmlmin:ignore\s*-->|<(pre|textarea|script|style)\b[^>]*>.*?<\/\1\s*>|<!--[\s\S]*?-->|<v:[\s\S]*?<\/v:[^>]+>/im
+    TOKEN = /<[^>"']*(?:(?:"[^"]*"|'[^']*')[^>"']*)*>/m
+
+    def initialize(options)
+      @options = options
+    end
+
+    def format(html)
+      output = html.dup
+      # Source and generated protection regions are restored byte for byte.
+      regions = []
+      prefix = "MJMLRBPRESERVE#{object_id}X"
+      prefix += "X" while html.include?(prefix)
+      output = output.gsub(/<!--\s*htmlmin:ignore\s*-->.*?<!--\s*htmlmin:ignore\s*-->/m) do |region|
+        regions << region.gsub(IGNORE, "")
+        "#{prefix}#{regions.length - 1}X"
+      end
+      raw_regions = []
+      output = output.gsub(/<!--mjml-rb:raw-start-->(.*?)<!--mjml-rb:raw-end-->/m) do
+        content = Regexp.last_match(1)
+        content = process_styles(content) if @options[:sanitize_styles]
+        raw_regions << content
+        "#{prefix}R#{raw_regions.length - 1}X"
+      end
+      output = process_styles(output) if @options[:sanitize_styles] || (@options[:minify] && @options[:minify_options].fetch(:minify_css, true))
+      if @options[:minify] || @options[:beautify]
+        protected = []
+        output = output.gsub(PROTECTED) do |part|
+          protected << part
+          "<#{prefix}P#{protected.length - 1}X/>"
+        end
+        # Whitespace inside text and quoted attributes is significant. Only
+        # whitespace between structural tags is eligible for formatting.
+        output = output.gsub(/(>)([\t\r\n ]*)(?=<)/) do
+          @options[:minify] ? ">" : ">\n"
+        end
+        protected.each_with_index { |part, index| output = output.gsub("<#{prefix}P#{index}X/>") { part } }
+      end
+      raw_regions.each_with_index { |part, index| output = output.gsub("#{prefix}R#{index}X") { part } }
+      regions.each_with_index { |part, index| output = output.gsub("#{prefix}#{index}X") { part } }
+      output.gsub(IGNORE, "")
+    end
+
+    private
+
+    def process_styles(html)
+      pattern = /<(script|textarea|pre)\b[^>]*>.*?<\/\1\s*>|<!--.*?-->|(<style\b[^>]*>)(.*?)(<\/style\s*>)|#{TOKEN}/mi
+      html.gsub(pattern) do |part|
+        if Regexp.last_match(1) || part.start_with?("<!--")
+          part
+        elsif Regexp.last_match(2)
+          opening, css, closing = Regexp.last_match.captures[1..3]
+          "#{opening}#{process_css(css)}#{closing}"
+        else
+          part.gsub(/(\sstyle\s*=\s*)(["'])(.*?)\2/mi) do
+            name, quote, css = Regexp.last_match.captures
+            "#{name}#{quote}#{process_css(css)}#{quote}"
+          end
+        end
+      end
+    end
+
+    def process_css(css)
+      variables = []
+      kinds = []
+      token_prefix = "mjmlrbvariable"
+      token_prefix += "x" while css.include?(token_prefix)
+      syntaxes = @options[:template_syntax]
+      unless syntaxes.is_a?(Array) && syntaxes.all? { |syntax| syntax.is_a?(Hash) && (syntax[:prefix] || syntax['prefix']).is_a?(String) && (syntax[:suffix] || syntax['suffix']).is_a?(String) }
+        raise ArgumentError, "template_syntax must be an array of prefix/suffix objects"
+      end
+      syntaxes.each do |syntax|
+        prefix, suffix = syntax.values_at(:prefix, :suffix)
+        prefix ||= syntax['prefix']
+        suffix ||= syntax['suffix']
+        raise ArgumentError, "Template delimiters must not be empty" if prefix.empty? || suffix.empty?
+        pattern = /#{Regexp.escape(prefix)}.*?#{Regexp.escape(suffix)}/m
+        if @options[:sanitize_styles]
+          if css.scan(Regexp.new(Regexp.escape(prefix))).size != css.scan(Regexp.new(Regexp.escape(suffix))).size
+            raise ArgumentError, "Unbalanced template delimiters #{prefix.inspect}/#{suffix.inspect} in CSS"
+          end
+          rest = css.gsub(pattern, '')
+          if rest.include?(prefix) || rest.include?(suffix)
+            raise ArgumentError, "Unbalanced template delimiters #{prefix.inspect}/#{suffix.inspect} in CSS"
+          end
+        end
+        css = css.gsub(pattern) do |token|
+          match = Regexp.last_match
+          before, after = css[0...match.begin(0)].rstrip, css[match.end(0)..].lstrip
+          kinds << (after.start_with?(':') ? :property : before.end_with?(':') ? :value : :block)
+          variables << token
+          "#{token_prefix}#{variables.length - 1}token"
+        end
+      end
+      if @options[:sanitize_styles] && !@options[:allow_mixed_syntax] && kinds.include?(:block) && (kinds.include?(:value) || kinds.include?(:property))
+        raise ArgumentError, "Mixed variable syntax detected in CSS; set allow_mixed_syntax: true to allow it"
+      end
+      if @options[:minify] && @options[:minify_options].fetch(:minify_css, true)
+        # CSS strings and comments are tokens, not whitespace to collapse.
+        css = css.split(/("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\/\*.*?\*\/)/m).map.with_index do |part, index|
+          index.odd? ? part : part.gsub(/\s+/, ' ').gsub(/\s*([{};,])\s*/, '\1').gsub(/:\s+/, ':')
+        end.join.strip
+      end
+      variables.each_with_index { |value, index| css = css.gsub("#{token_prefix}#{index}token") { value } }
+      css
+    end
+  end
+end

data/lib/mjml-rb/node_compat.rb

@@ -0,0 +1,19 @@
+require "nokogiri"
+
+module MjmlRb
+  module NodeCompat
+    def tag_name
+      name
+    end
+
+    def line
+      element? && self["data-mjml-line"] ? self["data-mjml-line"].to_i : super
+    end
+
+    def file
+      self["data-mjml-file"]
+    end
+  end
+end
+
+Nokogiri::XML::Node.prepend(MjmlRb::NodeCompat)

data/lib/mjml-rb/options.rb

@@ -0,0 +1,81 @@
+module MjmlRb
+  # Shared by the library, JSON configuration and CLI. Canonicalization happens
+  # before merging layers, so aliases never accidentally change precedence.
+  module Options
+    DEFAULTS = {
+      beautify: false, minify: false, keep_comments: true,
+      ignore_includes: true, printer_support: false, preprocessors: [],
+      validation_level: "soft", file_path: ".", actual_path: ".",
+      minify_options: {}, sanitize_styles: false,
+      template_syntax: [{prefix: "{{", suffix: "}}"}, {prefix: "[[", suffix: "]]"}],
+      allow_mixed_syntax: false, use_mjml_config_options: false
+    }.freeze
+    KEYS = (DEFAULTS.keys + %i[lang dir fonts include_path mjml_config_path juice_options juice_preserve_tags]).freeze
+
+    def self.key(key)
+      key.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').tr("-", "_").downcase.to_sym
+    end
+
+    def self.normalize(options)
+      raise ArgumentError, "Options must be an object" unless options.is_a?(Hash)
+
+      result = options.each_with_object({}) do |(name, value), normalized|
+        canonical = key(name)
+        if canonical == :allow_includes
+          canonical = :ignore_includes
+          raise ArgumentError, "allowIncludes must be true or false" unless [true, false].include?(value)
+          value = !value
+        end
+        if normalized.key?(canonical) && normalized[canonical] != value
+          raise ArgumentError, "Conflicting values for #{canonical}"
+        end
+        normalized[canonical] = value
+      end
+      unknown = result.keys - KEYS
+      raise ArgumentError, "Unknown option(s): #{unknown.join(', ')}" unless unknown.empty?
+      if result.key?(:validation_level) && !%w[soft strict skip].include?(result[:validation_level].to_s)
+        raise ArgumentError, "Invalid validation_level: #{result[:validation_level].inspect}"
+      end
+      %i[beautify minify keep_comments ignore_includes printer_support sanitize_styles allow_mixed_syntax use_mjml_config_options].each do |name|
+        next unless result.key?(name)
+        raise ArgumentError, "#{name} must be true or false" unless [true, false].include?(result[name])
+      end
+      %i[juice_options juice_preserve_tags].each do |name|
+        next unless result.key?(name)
+        raise ArgumentError, "Unsupported option: #{name}; the Ruby CSS inliner does not implement Juice options" unless result[name].nil? || result[name] == {}
+      end
+      if result.key?(:include_path) && !(result[:include_path].is_a?(String) || (result[:include_path].is_a?(Array) && result[:include_path].all? { |p| p.is_a?(String) }))
+        raise ArgumentError, "include_path must be a string or an array of strings"
+      end
+      if result.key?(:preprocessors) && !(result[:preprocessors].is_a?(Array) && result[:preprocessors].all? { |processor| processor.respond_to?(:call) })
+        raise ArgumentError, "preprocessors must be an array of callables"
+      end
+      if result.key?(:template_syntax)
+        syntaxes = result[:template_syntax]
+        valid = syntaxes.is_a?(Array) && syntaxes.all? do |syntax|
+          syntax.is_a?(Hash) && %i[prefix suffix].all? do |part|
+            value = syntax[part] || syntax[part.to_s]
+            value.is_a?(String) && !value.empty?
+          end
+        end
+        raise ArgumentError, "template_syntax must be an array of non-empty prefix/suffix objects" unless valid
+      end
+      if result.key?(:minify_options)
+        value = result[:minify_options]
+        raise ArgumentError, "minify_options must be an object" unless value.is_a?(Hash)
+        result[:minify_options] = value.each_with_object({}) do |(name, setting), memo|
+          canonical = name.to_s.gsub(/[^a-z]/i, "").downcase
+          raise ArgumentError, "Unsupported minify_options key: #{name}" unless canonical == "minifycss"
+          raise ArgumentError, "minifyCss must be true or false" unless [true, false].include?(setting)
+          raise ArgumentError, "Conflicting minifyCss values" if memo.key?(:minify_css) && memo[:minify_css] != setting
+          memo[:minify_css] = setting
+        end
+      end
+      result
+    end
+
+    def self.merge(base, overrides)
+      base.merge(overrides).merge(minify_options: (base[:minify_options] || {}).merge(overrides[:minify_options] || {}))
+    end
+  end
+end

data/lib/mjml-rb/parser.rb

@@ -1,22 +1,17 @@
 require "nokogiri"
+require "uri"
+require_relative "options"
 
-require_relative "ast_node"
+require_relative "node_compat"
 
 module MjmlRb
   class Parser
     HTML_VOID_TAGS = %w[area base br col embed hr img input link meta param source track wbr].freeze
 
-    # Ending-tag components whose inner HTML is preserved as raw content via CDATA
-    # wrapping, matching upstream npm's endingTag behavior. mj-table is excluded
-    # because its component needs structural AST access for attribute normalization.
-    # mj-carousel-image is excluded because it has no meaningful inner content.
-    ENDING_TAGS_FOR_CDATA = %w[
-      mj-accordion-text mj-accordion-title mj-button
-      mj-navbar-link mj-raw mj-text
-    ].freeze
+    ParseResult = Struct.new(:ast, :diagnostics, :dependencies, keyword_init: true)
 
-    # Pre-compiled regex patterns to avoid rebuilding on every call
-    ENDING_TAG_OPEN_RE = /<(#{ENDING_TAGS_FOR_CDATA.map { |t| Regexp.escape(t) }.join("|")})(\s[^<>]*?)?(?<!\/)>/mi.freeze
+    # mj-table retains structural access for its attribute normalization.
+    STRUCTURAL_ENDING_TAGS = %w[mj-table mj-carousel-image].freeze
 
     VOID_TAG_CLOSING_BR_RE = %r{</br\s*>}i.freeze
     VOID_TAG_CLOSING_OTHER_RE = /<\/(#{(HTML_VOID_TAGS - ["br"]).join("|")})\s*>/i.freeze
@@ -33,45 +28,69 @@ module MjmlRb
     ].freeze
 
     class ParseError < StandardError
-      attr_reader :line
+      attr_reader :line, :file, :dependencies
 
-      def initialize(message, line: nil)
+      def initialize(message, line: nil, file: nil, dependencies: [])
         super(message)
         @line = line
+        @file = file
+        @dependencies = dependencies
       end
     end
 
     # Errors collected during include expansion (missing files, etc.)
     # Read after calling #parse to retrieve non-fatal include issues.
-    attr_reader :include_errors
+    attr_reader :include_errors, :dependencies
+
+    def parse_result(mjml, options = {})
+      worker = self.class.new
+      ast = worker.parse(mjml, options)
+      ParseResult.new(ast: ast, diagnostics: worker.include_errors.freeze, dependencies: worker.dependencies.uniq.freeze)
+    end
 
     def parse(mjml, options = {})
       @include_errors = []
+      @dependencies = []
+      @ending_tags = @ending_tag_open_re = nil
       opts = normalize_options(options)
       xml = apply_preprocessors(mjml.to_s, opts[:preprocessors])
       xml = wrap_ending_tags_in_cdata(xml)
-      xml = normalize_html_void_tags(xml)
+      xml = outside_cdata(xml) { |part| normalize_html_void_tags(part) }
       xml = expand_includes(xml, opts) unless opts[:ignore_includes]
 
       xml = sanitize_bare_ampersands(xml)
       xml = replace_html_entities(xml)
       doc = Nokogiri::XML(xml) { |config| config.strict }
+      doc.xpath("//mj-include").each(&:remove) if opts[:ignore_includes]
       normalize_root_head_elements(doc)
-      element_to_ast(doc.root, keep_comments: opts[:keep_comments])
+      prepare_node(doc.root, keep_comments: opts[:keep_comments])
+      doc.root
     rescue Nokogiri::XML::SyntaxError => e
-      raise ParseError.new("XML parse error: #{e.message}")
+      raise xml_parse_error(e, opts[:actual_path])
     end
 
     private
 
     def normalize_options(options)
-      {
-        keep_comments: options[:keep_comments],
-        preprocessors: Array(options[:preprocessors]),
-        ignore_includes: !!options[:ignore_includes],
-        file_path: options[:file_path] || ".",
-        actual_path: options[:actual_path] || "."
-      }
+      opts = Options::DEFAULTS.merge(Options.normalize(options))
+      base = File.expand_path(opts[:file_path])
+      base = File.dirname(base) if File.file?(base)
+      roots = [base] + Array(opts[:include_path]).map { |root| File.expand_path(root, base) }
+      opts.merge(file_path: base, allowed_roots: roots.filter_map { |root| File.realpath(root) rescue nil })
+    end
+
+    def ending_tags
+      @ending_tags ||= MjmlRb.component_registry.ending_tags - STRUCTURAL_ENDING_TAGS
+    end
+
+    def ending_tag_open_re
+      @ending_tag_open_re ||= /<(#{ending_tags.map { |tag| Regexp.escape(tag) }.join("|")})(\s[^<>]*?)?(?<!\/)>/mi
+    end
+
+    def outside_cdata(content)
+      content.split(/(<!\[CDATA\[.*?\]\]>)/m).map do |part|
+        part.start_with?("<![CDATA[") ? part : yield(part)
+      end.join
     end
 
     def apply_preprocessors(xml, preprocessors)
@@ -82,50 +101,55 @@ module MjmlRb
 
     def expand_includes(xml, options, included_in = [])
       xml = wrap_ending_tags_in_cdata(xml)
-      xml = normalize_html_void_tags(xml)
+      xml = outside_cdata(xml) { |part| normalize_html_void_tags(part) }
       doc = parse_xml(sanitize_bare_ampersands(xml))
       includes = doc.xpath("//mj-include")
-      return xml if includes.empty?
+      return xml if includes.empty? && included_in.empty?
+
+      annotate_include_source(doc.root, options[:actual_path]) unless included_in.empty?
 
-      css_includes = []
       head_includes = []
 
-      includes.reverse_each do |include_node|
+      includes.each do |include_node|
         path_attr = include_node["path"]
-        raise ParseError, "mj-include path is required" if path_attr.to_s.empty?
-
-        include_type = include_node["type"].to_s
-        parent = include_node.parent
-
-        resolved_path = begin
-          resolve_include_path(path_attr, options[:actual_path], options[:file_path])
-        rescue Errno::ENOENT
-          nil
+        if path_attr.to_s.empty?
+          raise ParseError.new("mj-include path is required", line: include_node.line, file: options[:actual_path], dependencies: @dependencies)
         end
 
-        include_content = resolved_path ? File.read(resolved_path) : nil
+        include_type = include_node["type"].to_s
 
-        if include_content.nil?
-          display_path = resolved_path || File.expand_path(path_attr, options[:file_path].to_s)
-          @include_errors << {
-            message: "mj-include fails to read file : #{path_attr} at #{display_path}",
-            tag_name: "mj-include",
-            file: display_path
-          }
+        begin
+          resolved_path = resolve_include_path(path_attr, options)
+          @dependencies << resolved_path
+          include_content = File.read(resolved_path)
+        rescue IncludeDenied
+          @include_errors << include_diagnostic(include_node, options, "include-denied", "mj-include denied: #{path_attr}")
+          replacement = Nokogiri::XML::Node.new("mj-raw", doc)
+          replacement.add_child(Nokogiri::XML::CDATA.new(doc, "<!-- mj-include denied -->"))
+          include_node.replace(replacement)
+          next
+        rescue SystemCallError
+          @include_errors << include_diagnostic(include_node, options, "include", "mj-include fails to read file : #{path_attr} at #{resolved_path}")
           include_node.remove
           next
         end
 
         # Circular include detection
         if included_in.include?(resolved_path)
-          raise ParseError, "Circular inclusion detected on file : #{resolved_path}"
+          raise ParseError.new("Circular inclusion detected on file : #{resolved_path}", line: include_node.line, file: options[:actual_path], dependencies: @dependencies)
         end
 
         if include_type == "css"
-          # CSS includes get collected and added to mj-head later
-          css_inline = include_node["css-inline"].to_s
-          css_includes << { content: include_content, inline: css_inline == "inline" }
-          include_node.remove
+          style = Nokogiri::XML::Node.new("mj-style", doc)
+          style["inline"] = "inline" if include_node["css-inline"] == "inline"
+          style.add_child(Nokogiri::XML::CDATA.new(doc, include_content))
+          annotate_include_source(style, resolved_path)
+          if include_node.parent.name == "mj-head"
+            include_node.replace(style)
+          else
+            ensure_head(doc).add_child(style)
+            include_node.remove
+          end
           next
         end
 
@@ -133,13 +157,13 @@ module MjmlRb
                         %(<mj-raw><![CDATA[#{escape_cdata(include_content)}]]></mj-raw>)
                       else
                         prepared = prepare_mjml_include_document(include_content)
-                        prepared = wrap_ending_tags_in_cdata(normalize_html_void_tags(prepared))
+                        prepared = wrap_ending_tags_in_cdata(prepared)
                         expanded = expand_includes(prepared, options.merge(
                           actual_path: resolved_path,
                           file_path: File.dirname(resolved_path)
                         ), included_in + [resolved_path])
                         body_children, include_head_children = extract_mjml_include_children(expanded)
-                        head_includes.unshift(*include_head_children)
+                        head_includes.push(*include_head_children)
                         body_children
                       end
 
@@ -161,12 +185,9 @@ module MjmlRb
 
       inject_head_includes(doc, head_includes) unless head_includes.empty?
 
-      # Inject CSS includes into mj-head
-      unless css_includes.empty?
-        inject_css_includes(doc, css_includes)
-      end
-
       doc.root.to_xml(save_with: Nokogiri::XML::Node::SaveOptions::AS_XML | Nokogiri::XML::Node::SaveOptions::NO_DECLARATION)
+    rescue Nokogiri::XML::SyntaxError => e
+      raise xml_parse_error(e, options[:actual_path])
     end
 
     def prepare_mjml_include_document(content)
@@ -196,18 +217,6 @@ module MjmlRb
       head_includes.each { |child| head.add_child(child) }
     end
 
-    def inject_css_includes(doc, css_includes)
-      head = ensure_head(doc)
-
-      # Add each CSS include as an mj-style element
-      css_includes.each do |css_include|
-        style_node = Nokogiri::XML::Node.new("mj-style", doc)
-        style_node["inline"] = "inline" if css_include[:inline]
-        style_node.add_child(Nokogiri::XML::CDATA.new(doc, css_include[:content]))
-        head.add_child(style_node)
-      end
-    end
-
     def ensure_head(doc)
       mjml_root = doc.root
       return unless mjml_root
@@ -280,7 +289,7 @@ module MjmlRb
       wrapped = +""
       cursor = 0
 
-      while (match = ENDING_TAG_OPEN_RE.match(content, cursor))
+      while (match = ending_tag_open_re.match(content, cursor))
         tag = match[1]
         attrs = match[2].to_s
         wrapped << content[cursor...match.begin(0)]
@@ -296,9 +305,7 @@ module MjmlRb
         if inner.include?("<![CDATA[")
           wrapped << "<#{tag}#{attrs}>#{inner}</#{tag}>"
         else
-          # Pre-process content: normalize void tags and sanitize bare ampersands
-          # before wrapping in CDATA, so the raw HTML is well-formed for output.
-          prepared = sanitize_bare_ampersands(normalize_html_void_tags(inner))
+          prepared = inner
           wrapped << "<#{tag}#{attrs}><![CDATA[#{escape_cdata(prepared)}]]></#{tag}>"
         end
 
@@ -355,7 +362,7 @@ module MjmlRb
     # (e.g. &amp; &#123; &#x1F;).  This lets the XML parser handle HTML-ish
     # content such as "Terms & Conditions" which is common in email templates.
     def sanitize_bare_ampersands(content)
-      content.gsub(BARE_AMPERSAND_RE, "&amp;")
+      outside_cdata(content) { |part| part.gsub(BARE_AMPERSAND_RE, "&amp;") }
     end
 
     # Replace HTML named entities (e.g. &nbsp;, &copy;) with their numeric
@@ -364,12 +371,14 @@ module MjmlRb
     # HTML must be converted to numeric form for the XML parser to accept them.
     # Uses Nokogiri's built-in HTML entity lookup table.
     def replace_html_entities(content)
-      content.gsub(/&([a-zA-Z][a-zA-Z0-9]*);/) do |match|
-        name = ::Regexp.last_match(1)
-        next match if XML_PREDEFINED_ENTITIES.include?(name)
+      outside_cdata(content) do |part|
+        part.gsub(/&([a-zA-Z][a-zA-Z0-9]*);/) do |match|
+          name = ::Regexp.last_match(1)
+          next match if XML_PREDEFINED_ENTITIES.include?(name)
 
-        codepoint = Nokogiri::HTML::NamedCharacters[name]
-        codepoint ? "&##{codepoint};" : match
+          codepoint = Nokogiri::HTML::NamedCharacters[name]
+          codepoint ? "&##{codepoint};" : match
+        end
       end
     end
 
@@ -383,81 +392,99 @@ module MjmlRb
 
       if (element.name.start_with?("mj-") || element.name == "mjml") && !element["data-mjml-file"]
         element["data-mjml-file"] = file_path
+        element["data-mjml-line"] = element.line.to_s
       end
       element.element_children.each { |child| annotate_include_source(child, file_path) }
     end
 
-    def resolve_include_path(include_path, actual_path, file_path)
-      include_path = include_path.to_s
-      return include_path if File.absolute_path(include_path) == include_path && File.file?(include_path)
-
-      candidates = []
-      candidates << File.expand_path(include_path, File.dirname(actual_path.to_s))
-      candidates << File.expand_path(include_path, file_path.to_s)
-      candidates << File.expand_path(include_path, Dir.pwd)
+    class IncludeDenied < StandardError; end
 
-      existing = candidates.find { |candidate| File.file?(candidate) }
-      return existing if existing
+    def include_diagnostic(node, options, type, message)
+      {type: type, message: message, formatted_message: message,
+       tag_name: "mj-include", line: node.line, file: options[:actual_path]}
+    end
 
-      raise Errno::ENOENT, include_path
+    def resolve_include_path(path, options)
+      decoded = path.to_s
+      10.times do
+        next_value = URI::DEFAULT_PARSER.unescape(decoded)
+        break if next_value == decoded
+        decoded = next_value
+      end
+      if decoded.include?("\0") || decoded.start_with?("/", "\\") || decoded.match?(/\A[A-Za-z]:/)
+        raise IncludeDenied
+      end
+      base = options[:file_path]
+      candidate = File.expand_path(decoded, base)
+      # Resolve every existing ancestor, including symlinks of missing targets.
+      ancestor = candidate
+      ancestor = File.dirname(ancestor) until File.exist?(ancestor) || File.symlink?(ancestor) || ancestor == File.dirname(ancestor)
+      canonical = File.realpath(ancestor)
+      allowed = options[:allowed_roots].any? { |root| canonical == root || canonical.start_with?(File.join(root, "")) }
+      raise IncludeDenied unless allowed
+      File.exist?(candidate) ? File.realpath(candidate) : candidate
+    rescue Errno::ELOOP
+      raise IncludeDenied
     end
 
-    def element_to_ast(element, keep_comments:)
+    def prepare_node(element, keep_comments:)
       raise ParseError, "Missing XML root element" unless element
 
-      # Extract metadata annotations (added by annotate_include_source)
-      # and strip them from the public attributes hash.
-      # Line numbers come from Nokogiri's native node.line.
-      meta_line = element.line
-      meta_file = element["data-mjml-file"]
-      attrs = {}
-      element.attributes.each do |name, attr|
-        attrs[name] = attr.value unless name.start_with?("data-mjml-")
+      # Mark non-mj elements for raw HTML handling
+      unless element.name.start_with?("mj-") || element.name == "mjml"
+        element["data-mjml-raw"] = "true"
       end
-      attrs["data-mjml-raw"] = "true" unless element.name.start_with?("mj-") || element.name == "mjml"
-
-      # For ending-tag elements whose content was wrapped in CDATA, store
-      # the raw HTML directly as content instead of parsing structurally.
-      if ENDING_TAGS_FOR_CDATA.include?(element.name)
-        raw_content = element.children.select { |c| c.cdata? || c.text? }.map(&:content).join
-        return AstNode.new(
-          tag_name: element.name,
-          attributes: attrs,
-          children: [],
-          content: raw_content.empty? ? nil : raw_content,
-          line: meta_line,
-          file: meta_file
-        )
+
+      # For ending-tag elements whose content was wrapped in CDATA,
+      # mark them so raw_inner knows to extract content directly.
+      if ending_tags.include?(element.name)
+        element["data-mjml-ending-tag"] = "true"
+        unless keep_comments
+          element.children.each do |child|
+            next unless child.cdata? || child.text?
+            child.content = strip_source_comments(child.content)
+          end
+        end
+        return
       end
 
-      children = element.children.each_with_object([]) do |child, memo|
+      # Strip ignorable whitespace text nodes, unwanted comments,
+      # and recurse into element children.
+      element.children.to_a.each do |child|
         if child.element?
-          memo << element_to_ast(child, keep_comments: keep_comments)
+          prepare_node(child, keep_comments: keep_comments)
         elsif child.text? || child.cdata?
           text = child.content
-          next if text.empty?
-          next if text.strip.empty? && ignorable_whitespace_text?(text, parent_element_name: element.name)
-
-          memo << AstNode.new(tag_name: "#text", content: text)
+          if text.empty? || (text.strip.empty? && ignorable_whitespace_text?(text, parent_element_name: element.name))
+            child.remove
+          end
         elsif child.comment?
-          memo << AstNode.new(tag_name: "#comment", content: child.content) if keep_comments
+          child.remove unless keep_comments || child.content.match?(/\A(?:\[if|<!\[endif|\s*htmlmin:ignore)/i)
+        else
+          child.remove
         end
       end
+    end
 
-      AstNode.new(
-        tag_name: element.name,
-        attributes: attrs,
-        children: children,
-        line: meta_line,
-        file: meta_file
-      )
+    def strip_source_comments(content)
+      content.gsub(/<(script|style|textarea)\b[^>]*>.*?<\/\1\s*>|<!--.*?-->/mi) do |part|
+        if !part.start_with?("<!--") || part.match?(/\A<!--(?:\[if|<!\[endif|\s*htmlmin:ignore)/i)
+          part
+        else
+          ""
+        end
+      end
     end
 
-    # Lenient XML parse used during include expansion and intermediate steps.
-    # Errors are collected but do not raise; the final strict parse in #parse
-    # will surface any real issues.
     def parse_xml(xml)
-      Nokogiri::XML(replace_html_entities(xml))
+      Nokogiri::XML(replace_html_entities(xml)) { |config| config.strict }
+    end
+
+    def xml_parse_error(error, file)
+      # Nokogiri's aggregate exception has no #line; retain the first reported
+      # location while leaving its complete diagnostic message intact.
+      line = error.line || error.message[/^(\d+):\d+:/, 1]&.to_i
+      ParseError.new("XML parse error: #{error.message}", line: line, file: file, dependencies: @dependencies)
     end
 
     def ignorable_whitespace_text?(text, parent_element_name:)