activemail 1.2.3 → 2.1.0

data/lib/activemail/inliner/premailer.rb

@@ -12,10 +12,11 @@ module ActiveMail
       def inline(html)
         # premailer is a hard runtime dependency (the default inliner), so require
         # can't fail — unlike the optional Roadie adapter, which guards LoadError.
-        require 'premailer'
+        # Loaded on first use: premailer is slow to load and a :roadie or :null host never needs it.
+        require_relative 'premailer/document'
         # warn_level NONE: premailer's un-inlinable-CSS warnings are noise at delivery
         # time; the quality layer is where coverage gaps should surface.
-        ::Premailer.new(html, with_html_string: true, warn_level: ::Premailer::Warnings::NONE).to_inline_css
+        Document.new(html, with_html_string: true, warn_level: ::Premailer::Warnings::NONE).to_inline_css
       end
     end
   end

data/lib/activemail/inliner/roadie.rb

@@ -22,7 +22,7 @@ module ActiveMail
         require 'roadie'
       rescue LoadError
         # Unify on Inliner::Error (LoadError is not a StandardError, so the
-        # interceptor's rescue would otherwise miss it); the LoadError is #cause.
+        # Pipeline's rescue would otherwise miss it); the LoadError is #cause.
         raise ActiveMail::Inliner::Error, "ActiveMail::Inliner::Roadie requires the 'roadie' gem. Add it to your Gemfile."
       end
     end

data/lib/activemail/inliner.rb

@@ -0,0 +1,33 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+require_relative 'inliner/base'
+require_relative 'inliner/premailer'
+require_relative 'inliner/roadie'
+require_relative 'inliner/null'
+
+module ActiveMail
+  module Inliner
+    extend T::Sig
+
+    ADAPTERS = T.let(
+      { premailer: Premailer, roadie: Roadie, null: Null }.freeze,
+      T::Hash[Symbol, T.class_of(Base)]
+    )
+
+    Setting = T.type_alias { T.any(Symbol, Base, T.class_of(Base)) }
+
+    sig { params(setting: Setting).returns(Base) }
+    def self.resolve(setting)
+      return setting if setting.is_a?(Base)
+      return setting.new if setting.is_a?(Class) && setting < Base
+
+      adapter = ADAPTERS[setting] if setting.is_a?(Symbol)
+      return adapter.new if adapter
+
+      raise ArgumentError, "unknown inliner #{setting.inspect}, expected one of #{ADAPTERS.keys.inspect}, an Inliner::Base subclass, or an instance"
+    end
+  end
+end

data/lib/activemail/parse_error_reporter.rb

@@ -7,19 +7,20 @@ require_relative 'libxml'
 
 module ActiveMail
   # Surfaces libxml2 recover-mode repairs that would otherwise silently change
-  # the rendered email, honoring ActiveMail.configuration.on_parse_error.
+  # the rendered email, honoring the config's on_parse_error.
   class ParseErrorReporter
     extend T::Sig
 
-    sig { params(known_tags: T::Array[String]).void }
-    def initialize(known_tags)
+    sig { params(known_tags: T::Array[String], config: ActiveMail::Configuration).void }
+    def initialize(known_tags, config)
+      @config = config
       # dup.freeze: the caller's array stays decoupled and cannot be mutated under us.
       @known_tags = T.let(known_tags.dup.freeze, T::Array[String])
     end
 
     sig { params(errors: T::Array[Nokogiri::XML::SyntaxError]).void }
     def call(errors)
-      mode = ::ActiveMail.configuration.on_parse_error
+      mode = @config.on_parse_error
       return if mode == :ignore
 
       relevant = errors.reject { |error| known_tag_error?(error) }

data/lib/activemail/pipeline.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module ActiveMail
+  module Pipeline
+    extend T::Sig
+
+    sig { params(html: String, config: ActiveMail::Configuration).returns(String) }
+    def self.call(html, config: ActiveMail.configuration)
+      inline(config.resolved_inliner, config.core.transpile(html))
+    end
+
+    sig { params(inliner: ActiveMail::Inliner::Base, html: String).returns(String) }
+    def self.inline(inliner, html)
+      inliner.inline(html)
+    rescue ActiveMail::Inliner::Error
+      raise
+    rescue StandardError => e
+      # A silently non-inlined mail is worse than a failed one.
+      raise ActiveMail::Inliner::Error, "[#{inliner.class}] CSS inlining failed: #{e.message}"
+    end
+    private_class_method :inline
+  end
+end

data/lib/activemail/quality/builtin_message_rules.rb

@@ -0,0 +1,58 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+require_relative 'preview_renderer'
+require_relative 'rule'
+
+module ActiveMail
+  module Quality
+    # The built-in rules that read the Mail message (subject, text part) rather than the HTML.
+    class BuiltinMessageRules
+      extend T::Sig
+
+      sig { returns(T::Array[Rule]) }
+      def rules
+        [
+          Rule.message(:translation_missing_text) { |mail| translation_missing_text_message(mail) },
+          Rule.message(:html_part_present) { |mail| html_part_present_message(mail) },
+          Rule.message(:text_part_present) { |mail| text_part_present_message(mail) },
+          Rule.message(:text_part_plain) { |mail| text_part_plain_message(mail) },
+          Rule.message(:text_entities) { |mail| text_entities_message(mail) }
+        ]
+      end
+
+      private
+
+      sig { params(mail: T.untyped).returns(T.nilable(String)) }
+      def text_entities_message(mail)
+        found = PreviewRenderer.text_body(mail).scan(BuiltinRules::HTML_ENTITY).uniq
+        "text/plain part contains HTML entities: #{found.first(3).join(', ')}" unless found.empty?
+      end
+
+      sig { params(mail: T.untyped).returns(T.nilable(String)) }
+      def translation_missing_text_message(mail)
+        text = "#{mail.subject}\n#{PreviewRenderer.text_body(mail)}"
+        'subject or text part contains a missing i18n translation' if text.match?(BuiltinRules::MISSING_TRANSLATION)
+      end
+
+      sig { params(mail: T.untyped).returns(T.nilable(String)) }
+      def html_part_present_message(mail)
+        'message has no HTML part' if PreviewRenderer.html_body(mail).empty?
+      end
+
+      sig { params(mail: T.untyped).returns(T.nilable(String)) }
+      def text_part_present_message(mail)
+        return if mail.multipart? && !PreviewRenderer.text_body(mail).strip.empty?
+
+        'message must be multipart with a non-empty text/plain part'
+      end
+
+      sig { params(mail: T.untyped).returns(T.nilable(String)) }
+      def text_part_plain_message(mail)
+        'text/plain part contains HTML markup' if PreviewRenderer.text_body(mail).match?(BuiltinRules::MARKUP_IN_TEXT)
+      end
+    end
+  end
+end

data/lib/activemail/quality/builtin_rules.rb

@@ -0,0 +1,165 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'sorbet-runtime'
+
+require_relative '../libxml'
+require_relative 'builtin_message_rules'
+require_relative 'preview_renderer'
+require_relative 'rule'
+
+module ActiveMail
+  module Quality
+    class BuiltinRules
+      extend T::Sig
+
+      NAMES = T.let(
+        %i[
+          max_bytes parse_error table_role img_alt lang min_full_doc_bytes translation_missing single_root
+          translation_missing_text html_part_present text_part_present text_part_plain
+          title anchor_href placeholder unsupported_color text_entities
+        ].freeze,
+        T::Array[Symbol]
+      )
+      MARKUP_IN_TEXT = %r{<(?:table|div|span|p|br|a)[\s>/]}i
+      MISSING_TRANSLATION = /translation[ _]missing/i
+      # An unresolved `{{variable}}` of a user-editable template; public so a host can refuse it before sending.
+      PLACEHOLDER = /\{\{[^{}]+\}\}/
+      # Clients drop or mangle these CSS color forms in a style attribute.
+      UNSUPPORTED_COLOR = /rgba?\([^)]*%[^)]*\)|hsla?\(|color-mix\(|\bvar\(/i
+      HTML_ENTITY = /&(?:[a-z][a-z0-9]*|#\d+|#x\h+);/i
+      STYLE_AND_SCRIPT = %r{<(style|script)\b[\s\S]*?</\1\s*>}i
+      ROOTS = T.let({ html: /<html[\s>]/i, body: /<body[\s>]/i }.freeze, T::Hash[Symbol, Regexp])
+
+      sig { params(max_bytes: Integer, min_full_doc_bytes: Integer).void }
+      def initialize(max_bytes:, min_full_doc_bytes:)
+        # A non-positive threshold would silently disable (or invert) a check.
+        @max_bytes = T.let(::ActiveMail.positive_integer!(:max_bytes, max_bytes), Integer)
+        @min_full_doc_bytes = T.let(::ActiveMail.positive_integer!(:min_full_doc_bytes, min_full_doc_bytes), Integer)
+      end
+
+      sig { returns(T::Array[Rule]) }
+      def rules
+        structure_rules + content_rules + BuiltinMessageRules.new.rules
+      end
+
+      private
+
+      sig { returns(T::Array[Rule]) }
+      def structure_rules
+        [
+          Rule.html(:max_bytes) { |_doc, html| size_message(html) },
+          # The Core surfaces libxml2 repairs on input; the validation layer must not
+          # silently bless malformed *output* (mismatched tags, bad entities) before send.
+          Rule.html(:parse_error) { |doc, _html| parse_error_message(doc) },
+          Rule.html(:table_role) { |doc, _html| table_role_message(doc) },
+          Rule.html(:img_alt) { |doc, _html| img_alt_message(doc) },
+          Rule.html(:anchor_href) { |doc, _html| anchor_href_message(doc) },
+          Rule.html(:unsupported_color) { |doc, html| unsupported_color_message(doc, html) }
+        ]
+      end
+
+      sig { returns(T::Array[Rule]) }
+      def content_rules
+        [
+          Rule.html(:translation_missing) { |_doc, html| translation_missing_message(html) },
+          Rule.html(:single_root) { |_doc, html| single_root_messages(html) },
+          Rule.html(:min_full_doc_bytes) { |_doc, html| min_full_doc_message(html) },
+          Rule.html(:lang) { |doc, html| lang_message(doc, html) },
+          Rule.html(:title) { |doc, html| title_message(doc, html) },
+          Rule.html(:placeholder) { |_doc, html| placeholder_message(html) }
+        ]
+      end
+
+      sig { params(html: String).returns(T.nilable(String)) }
+      def size_message(html)
+        return if html.bytesize <= @max_bytes
+
+        "HTML is #{html.bytesize} bytes, exceeds #{@max_bytes} (Gmail clipping)"
+      end
+
+      sig { params(doc: Nokogiri::XML::Document).returns(T.nilable(String)) }
+      def parse_error_message(doc)
+        errors = doc.errors.reject { |e| e.code == LIBXML_UNKNOWN_TAG_CODE }
+        return if errors.empty?
+
+        "malformed HTML: #{errors.first(3).map { |e| e.message.to_s.strip }.join('; ')}"
+      end
+
+      sig { params(doc: Nokogiri::XML::Document).returns(T.nilable(String)) }
+      def table_role_message(doc)
+        offenders = doc.css('table').count { |table| table['role'] != 'presentation' }
+        %(#{offenders} <table> missing role="presentation") unless offenders.zero?
+      end
+
+      sig { params(doc: Nokogiri::XML::Document).returns(T.nilable(String)) }
+      def img_alt_message(doc)
+        offenders = doc.css('img').count { |img| !img.key?('alt') }
+        "#{offenders} <img> missing an alt attribute" unless offenders.zero?
+      end
+
+      sig { params(doc: Nokogiri::XML::Document).returns(T.nilable(String)) }
+      def anchor_href_message(doc)
+        offenders = doc.css('a').count { |anchor| anchor['href'].to_s.strip.empty? }
+        "#{offenders} <a> without a href" unless offenders.zero?
+      end
+
+      # The raw-string pre-check keeps the per-node scan off the common, clean path.
+      sig { params(doc: Nokogiri::XML::Document, html: String).returns(T.nilable(String)) }
+      def unsupported_color_message(doc, html)
+        return unless html.match?(UNSUPPORTED_COLOR)
+
+        offenders = doc.xpath('//*[@style]').filter_map { |node| node['style'].to_s[UNSUPPORTED_COLOR] }
+        return if offenders.empty?
+
+        "#{offenders.size} inline style(s) use a color clients ignore (rgb(%), hsl, color-mix, var()): #{offenders.uniq.first(3).join(', ')}"
+      end
+
+      sig { params(html: String).returns(T.nilable(String)) }
+      def translation_missing_message(html)
+        'rendered HTML contains a missing i18n translation' if html.match?(MISSING_TRANSLATION)
+      end
+
+      # Counted on the raw string: libxml2 silently merges duplicate roots.
+      sig { params(html: String).returns(T::Array[String]) }
+      def single_root_messages(html)
+        ROOTS.filter_map do |tag, pattern|
+          count = html.scan(pattern).size
+          "#{count} <#{tag}> roots, expected at most one" if count > 1
+        end
+      end
+
+      sig { params(html: String).returns(T.nilable(String)) }
+      def min_full_doc_message(html)
+        return unless ::ActiveMail.full_document?(html) && html.bytesize < @min_full_doc_bytes
+
+        "full document is only #{html.bytesize} bytes (under #{@min_full_doc_bytes})"
+      end
+
+      sig { params(doc: Nokogiri::XML::Document, html: String).returns(T.nilable(String)) }
+      def lang_message(doc, html)
+        return unless ::ActiveMail.full_document?(html)
+
+        html_tag = doc.at_css('html')
+        lang = html_tag && html_tag['lang']
+        '<html> must declare a non-blank lang attribute' if lang.nil? || lang.strip.empty?
+      end
+
+      sig { params(doc: Nokogiri::XML::Document, html: String).returns(T.nilable(String)) }
+      def title_message(doc, html)
+        return unless ::ActiveMail.full_document?(html)
+
+        '<head> must contain a non-blank <title>' if doc.at_css('title')&.text.to_s.strip.empty?
+      end
+
+      sig { params(html: String).returns(T.nilable(String)) }
+      def placeholder_message(html)
+        return unless html.include?('{{')
+
+        found = html.gsub(STYLE_AND_SCRIPT, '').scan(PLACEHOLDER).uniq
+        "unresolved placeholder(s): #{found.first(3).join(', ')}" unless found.empty?
+      end
+    end
+  end
+end

data/lib/activemail/quality/configuration.rb

@@ -1,14 +1,22 @@
 # typed: strict
 # frozen_string_literal: true
 
+require 'i18n'
 require 'sorbet-runtime'
 
 require_relative 'guard'
+require_relative 'output_dir'
+require_relative 'output_filter'
+require_relative 'rule_exemptions'
 
 module ActiveMail
   module Quality
     class Configuration
       extend T::Sig
+      include RuleExemptions
+
+      FORMATS = T.let(%i[html text].freeze, T::Array[Symbol])
+      DEFAULT_LOCALES = T.let(->(_preview) { [I18n.default_locale] }, Proc)
 
       sig { returns(Guard) }
       attr_reader :guard
@@ -25,9 +33,7 @@ module ActiveMail
 
       sig { params(value: String).void }
       def output_dir=(value)
-        raise ArgumentError, 'output_dir must not be blank' if value.strip.empty?
-
-        @output_dir = value
+        @output_dir = OutputDir.validate!(value)
       end
 
       # Preview keys ("preview_name#email") that MUST render and pass the guard;
@@ -35,21 +41,110 @@ module ActiveMail
       # reported.
       sig { returns(T::Array[String]) }
       def required_previews
-        @required_previews.dup.freeze
+        @preview_keys.fetch(:required).dup.freeze
       end
 
-      sig { params(value: T.untyped).returns(T::Array[String]) }
+      sig { params(value: T.untyped).void }
       def required_previews=(value)
-        raise TypeError, "#{value.inspect} (#{value.class}) does not respond to 'to_a'" unless value.respond_to?(:to_a)
+        @preview_keys[:required] = preview_keys(value)
+      end
+
+      # Preview keys that may legitimately decline to send (NullMail); any other
+      # preview returning one is a violation.
+      sig { returns(T::Array[String]) }
+      def allow_declined
+        @preview_keys.fetch(:allow_declined).dup.freeze
+      end
+
+      sig { params(value: T.untyped).void }
+      def allow_declined=(value)
+        @preview_keys[:allow_declined] = preview_keys(value)
+      end
+
+      sig { params(key: String).returns(T::Boolean) }
+      def allow_declined?(key)
+        @preview_keys.fetch(:allow_declined).include?(key)
+      end
+
+      sig { returns(T.any(T::Array[Symbol], Proc)) }
+      attr_reader :locales
+
+      sig { params(value: T.untyped).void }
+      def locales=(value)
+        @locales = value.is_a?(Proc) ? value : normalize_locales(value)
+      end
+
+      sig { params(preview: T.untyped).returns(T::Array[Symbol]) }
+      def locales_for(preview)
+        value = @locales
+        value.is_a?(Proc) ? normalize_locales(value.call(preview)) : value
+      end
+
+      sig { returns(T::Array[Symbol]) }
+      def formats
+        @formats.dup.freeze
+      end
 
-        @required_previews = value.to_a.map(&:to_s)
+      sig { params(value: T.untyped).void }
+      def formats=(value)
+        raise TypeError, "formats must be an Array, got #{value.class}" unless value.is_a?(Array)
+
+        formats = value.map(&:to_sym)
+        unknown = formats - FORMATS
+        raise ArgumentError, "unknown format(s): #{unknown.inspect}, expected a subset of #{FORMATS.inspect}" unless unknown.empty?
+        raise ArgumentError, 'formats must not be empty' if formats.empty?
+
+        @formats = formats.uniq
+      end
+
+      # ->(preview, email, locale, &block) wrapping each rendering; it must call block.
+      sig { returns(T.nilable(Proc)) }
+      attr_reader :around_each
+
+      sig { params(value: T.untyped).void }
+      def around_each=(value)
+        raise TypeError, "around_each must be a Proc or nil, got #{value.class}" unless value.nil? || value.is_a?(Proc)
+
+        @around_each = value
+      end
+
+      # Applied to written files only: the Guard always sees the unfiltered content.
+      sig { returns(T::Array[Proc]) }
+      attr_reader :output_filters
+
+      sig { params(value: T.untyped).void }
+      def output_filters=(value)
+        raise TypeError, "output_filters must be an Array, got #{value.class}" unless value.is_a?(Array)
+
+        @output_filters = value.map { |filter| OutputFilter.coerce(filter) }
       end
 
       sig { void }
       def initialize
         @guard = T.let(Guard.new, Guard)
         @output_dir = T.let('tmp/activemail_previews', String)
-        @required_previews = T.let([], T::Array[String])
+        @preview_keys = T.let({ required: [], allow_declined: [] }, T::Hash[Symbol, T::Array[String]])
+        @locales = T.let(DEFAULT_LOCALES, T.any(T::Array[Symbol], Proc))
+        @formats = T.let(FORMATS, T::Array[Symbol])
+        @around_each = T.let(nil, T.nilable(Proc))
+        @output_filters = T.let([], T::Array[Proc])
+      end
+
+      private
+
+      sig { params(value: T.untyped).returns(T::Array[String]) }
+      def preview_keys(value)
+        raise TypeError, "#{value.inspect} (#{value.class}) does not respond to 'to_a'" unless value.respond_to?(:to_a)
+
+        value.to_a.map(&:to_s)
+      end
+
+      sig { params(value: T.untyped).returns(T::Array[Symbol]) }
+      def normalize_locales(value)
+        raise TypeError, "locales must be an Array, got #{value.class}" unless value.is_a?(Array)
+        raise ArgumentError, 'locales must not be empty' if value.empty?
+
+        value.map(&:to_sym)
       end
     end
   end