activemail 2.0.0 → 2.1.0

data/lib/activemail/inliner/premailer/document.rb

@@ -0,0 +1,100 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'digest'
+require 'premailer'
+require 'sorbet-runtime'
+
+module ActiveMail
+  module Inliner
+    class Premailer < Base
+      # Premailer re-parses every <style> block with css_parser on each email; the framework
+      # CSS never changes between two emails, so its rule sets are parsed once per fingerprint.
+      class Document < ::Premailer
+        extend T::Sig
+
+        # Mirrors the parser Premailer builds for these options.
+        PARSER_OPTIONS = T.let(
+          { absolute_paths: true, import: true, io_exceptions: false, rule_set_exceptions: true, allow_local_network: false }.freeze,
+          T::Hash[Symbol, T.untyped]
+        )
+
+        # FIFO-bounded and thread-safe: mailers render from several threads and a dev reload
+        # compiles new CSS under a new fingerprint.
+        class RuleSetCache
+          extend T::Sig
+
+          LIMIT = 16
+
+          sig { void }
+          def initialize
+            @entries = T.let({}, T::Hash[T.untyped, T.untyped])
+            @mutex = T.let(Mutex.new, Mutex)
+          end
+
+          sig { params(key: T.untyped, block: T.proc.returns(T.untyped)).returns(T.untyped) }
+          def fetch(key, &block)
+            @mutex.synchronize { @entries[key] } || store(key, block.call)
+          end
+
+          sig { void }
+          def clear
+            @mutex.synchronize { @entries.clear }
+          end
+
+          sig { returns(Integer) }
+          def size
+            @mutex.synchronize { @entries.size }
+          end
+
+          private
+
+          sig { params(key: T.untyped, value: T.untyped).returns(T.untyped) }
+          def store(key, value)
+            @mutex.synchronize do
+              @entries[key] = value
+              @entries.shift while @entries.size > LIMIT
+            end
+            value
+          end
+        end
+
+        class CachedParser < ::CssParser::Parser
+          extend T::Sig
+
+          sig { params(block: String, options: T::Hash[Symbol, T.untyped]).void }
+          def add_block!(block, options = {})
+            Document.rule_sets.fetch([Digest::SHA256.hexdigest(block), options]) { parse(block, options) }.each do |rule_set, media_types|
+              add_rule_set!(rule_set, media_types)
+            end
+          end
+
+          private
+
+          sig { params(block: String, options: T::Hash[Symbol, T.untyped]).returns(T::Array[T.untyped]) }
+          def parse(block, options)
+            parser = ::CssParser::Parser.new(PARSER_OPTIONS)
+            parser.add_block!(block, options)
+            rule_sets = T.let([], T::Array[T.untyped])
+            parser.each_rule_set { |rule_set, media_types| rule_sets << [rule_set, media_types] }
+            rule_sets
+          end
+        end
+
+        sig { returns(RuleSetCache) }
+        def self.rule_sets
+          @rule_sets ||= T.let(RuleSetCache.new, T.nilable(RuleSetCache))
+        end
+
+        protected
+
+        # Premailer exposes no hook for its parser: swap it before the <style> blocks are read.
+        sig { void }
+        def load_css_from_html!
+          T.unsafe(self).instance_variable_set(:@css_parser, CachedParser.new(PARSER_OPTIONS))
+          super
+        end
+      end
+    end
+  end
+end

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/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

@@ -5,6 +5,7 @@ require 'nokogiri'
 require 'sorbet-runtime'
 
 require_relative '../libxml'
+require_relative 'builtin_message_rules'
 require_relative 'preview_renderer'
 require_relative 'rule'
 
@@ -17,11 +18,18 @@ module ActiveMail
         %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 }
@@ -33,7 +41,7 @@ module ActiveMail
 
       sig { returns(T::Array[Rule]) }
       def rules
-        structure_rules + content_rules + message_rules
+        structure_rules + content_rules + BuiltinMessageRules.new.rules
       end
 
       private
@@ -46,7 +54,9 @@ module ActiveMail
           # 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(: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
 
@@ -56,17 +66,9 @@ module ActiveMail
           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) }
-        ]
-      end
-
-      sig { returns(T::Array[Rule]) }
-      def message_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.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
 
@@ -97,6 +99,23 @@ module ActiveMail
         "#{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)
@@ -127,27 +146,19 @@ module ActiveMail
         '<html> must declare a non-blank lang attribute' if lang.nil? || lang.strip.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?(MISSING_TRANSLATION)
-      end
+      sig { params(doc: Nokogiri::XML::Document, html: String).returns(T.nilable(String)) }
+      def title_message(doc, html)
+        return unless ::ActiveMail.full_document?(html)
 
-      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?
+        '<head> must contain a non-blank <title>' if doc.at_css('title')&.text.to_s.strip.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(html: String).returns(T.nilable(String)) }
+      def placeholder_message(html)
+        return unless html.include?('{{')
 
-      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?(MARKUP_IN_TEXT)
+        found = html.gsub(STYLE_AND_SCRIPT, '').scan(PLACEHOLDER).uniq
+        "unresolved placeholder(s): #{found.first(3).join(', ')}" unless found.empty?
       end
     end
   end

data/lib/activemail/quality/configuration.rb

@@ -6,11 +6,14 @@ 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)
@@ -38,14 +41,29 @@ 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
 
-        @required_previews = value.to_a.map(&:to_s)
+      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)) }
@@ -98,14 +116,14 @@ module ActiveMail
       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| output_filter(filter) }
+        @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))
@@ -114,6 +132,13 @@ module ActiveMail
 
       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)
@@ -121,16 +146,6 @@ module ActiveMail
 
         value.map(&:to_sym)
       end
-
-      sig { params(filter: T.untyped).returns(Proc) }
-      def output_filter(filter)
-        return filter if filter.is_a?(Proc)
-
-        pattern, replacement = filter if filter.is_a?(Array) && filter.size == 2
-        raise TypeError, "output filter must be a Proc or [Regexp, String], got #{filter.inspect}" unless pattern.is_a?(Regexp) && replacement.is_a?(String)
-
-        ->(content) { content.gsub(pattern, replacement) }
-      end
     end
   end
 end

data/lib/activemail/quality/guard.rb

@@ -30,33 +30,51 @@ module ActiveMail
       DEFAULT_MAX_BYTES = 102_400
       # A full HTML document smaller than this carries no real layout and is suspect.
       DEFAULT_MIN_FULL_DOC_BYTES = 1_024
+      NO_SKIP = T.let([].freeze, T::Array[Symbol])
 
       sig { params(max_bytes: Integer, min_full_doc_bytes: Integer, disable: T::Array[Symbol], rules: T::Array[Rule]).void }
       def initialize(max_bytes: DEFAULT_MAX_BYTES, min_full_doc_bytes: DEFAULT_MIN_FULL_DOC_BYTES, disable: [], rules: [])
         all = assemble_rules(BuiltinRules.new(max_bytes: max_bytes, min_full_doc_bytes: min_full_doc_bytes), disable, rules)
         @html_rules = T.let(all.select { |rule| rule.level == :html }, T::Array[Rule])
         @message_rules = T.let(all.select { |rule| rule.level == :message }, T::Array[Rule])
+        # A disabled built-in rule stays a known name: exempting a preview from it is harmless, not a typo.
+        @rule_names = T.let((DISABLEABLE + rules.map(&:name)).freeze, T::Array[Symbol])
       end
 
-      # A String only gets the HTML rules; a message gets both levels, except a declined send.
-      sig { params(html_or_message: T.untyped).returns(T::Array[Violation]) }
-      def violations(html_or_message)
-        return html_violations(html_or_message) if html_or_message.is_a?(String)
+      # A String only gets the HTML rules; a message gets both levels. A declined send
+      # (NullMail) has nothing to check, but it is a violation unless the caller expects it.
+      sig { params(html_or_message: T.untyped, allow_declined: T::Boolean, skip: T::Array[Symbol]).returns(T::Array[Violation]) }
+      def violations(html_or_message, allow_declined: false, skip: NO_SKIP)
+        check_skippable!(skip)
+        return html_violations(html_or_message, skip) if html_or_message.is_a?(String)
 
         mail = PreviewRenderer.mail(html_or_message)
-        return [] if PreviewRenderer.declined?(mail)
+        return declined_violations(allow_declined) if PreviewRenderer.declined?(mail)
 
         html = PreviewRenderer.html_body(mail)
-        (html.empty? ? [] : html_violations(html)) + apply(@message_rules, [mail])
+        (html.empty? ? [] : html_violations(html, skip)) + apply(@message_rules, [mail], skip)
       end
 
-      sig { params(html_or_message: T.untyped).returns(T::Boolean) }
-      def valid?(html_or_message)
-        violations(html_or_message).empty?
+      sig { params(html_or_message: T.untyped, allow_declined: T::Boolean, skip: T::Array[Symbol]).returns(T::Boolean) }
+      def valid?(html_or_message, allow_declined: false, skip: NO_SKIP)
+        violations(html_or_message, allow_declined: allow_declined, skip: skip).empty?
+      end
+
+      sig { params(skip: T::Array[Symbol]).void }
+      def check_skippable!(skip)
+        return if skip.empty?
+
+        unknown = skip - @rule_names
+        raise ArgumentError, "unknown rule(s) to skip: #{unknown.inspect}, expected a subset of #{@rule_names.inspect}" unless unknown.empty?
       end
 
       private
 
+      sig { params(allowed: T::Boolean).returns(T::Array[Violation]) }
+      def declined_violations(allowed)
+        allowed ? [] : [Violation.new(rule: :declined, message: 'the mailer declined to send (NullMail)')]
+      end
+
       sig { params(builtin: BuiltinRules, disable: T::Array[Symbol], custom: T::Array[Rule]).returns(T::Array[Rule]) }
       def assemble_rules(builtin, disable, custom)
         unknown = disable - DISABLEABLE
@@ -73,14 +91,16 @@ module ActiveMail
         rules
       end
 
-      sig { params(html: String).returns(T::Array[Violation]) }
-      def html_violations(html)
-        apply(@html_rules, [Nokogiri::HTML(html), html])
+      sig { params(html: String, skip: T::Array[Symbol]).returns(T::Array[Violation]) }
+      def html_violations(html, skip)
+        apply(@html_rules, [Nokogiri::HTML(html), html], skip)
       end
 
-      sig { params(rules: T::Array[Rule], args: T::Array[T.untyped]).returns(T::Array[Violation]) }
-      def apply(rules, args)
+      sig { params(rules: T::Array[Rule], args: T::Array[T.untyped], skip: T::Array[Symbol]).returns(T::Array[Violation]) }
+      def apply(rules, args, skip)
         rules.flat_map do |rule|
+          next [] if skip.include?(rule.name)
+
           rule.messages(args).map { |message| Violation.new(rule: rule.name, message: message) }
         end
       end

data/lib/activemail/quality/minitest.rb

@@ -8,9 +8,9 @@ module ActiveMail
     module Minitest
       extend T::Sig
 
-      sig { params(html_or_message: T.untyped, guard: Guard).void }
-      def assert_email_quality(html_or_message, guard: ActiveMail::Quality.guard)
-        assert_no_quality_violations(guard.violations(html_or_message))
+      sig { params(html_or_message: T.untyped, guard: Guard, allow_declined: T::Boolean, skip: T::Array[Symbol]).void }
+      def assert_email_quality(html_or_message, guard: ActiveMail::Quality.guard, allow_declined: false, skip: Guard::NO_SKIP)
+        assert_no_quality_violations(guard.violations(html_or_message, allow_declined: allow_declined, skip: skip))
       end
 
       sig do
@@ -27,16 +27,23 @@ module ActiveMail
         sig { params(guard: Guard).void }
         def assert_quality_for_all_previews(guard: ActiveMail::Quality.guard)
           config = ActiveMail::Quality.config
+          config.check_exemptions!(guard)
           cases = PreviewRenderer.cases(config)
           # A silent no-test run would look like everything passed.
           Kernel.warn('[activemail] assert_quality_for_all_previews: no previews discovered.') if cases.empty?
-          cases.each_with_index do |(preview, email, locale), i|
-            # Index prefix: distinct keys can normalize to the same method name.
-            name = "test_#{i}_#{PreviewRenderer.key(preview, email).gsub(/\W/, '_')}_#{locale}_email_quality"
-            T.unsafe(self).define_method(name) do
-              violations = T.unsafe(self).send(:render_preview_or_skip, preview, email, locale, guard, config.required_previews)
-              T.unsafe(self).send(:assert_no_quality_violations, violations)
-            end
+          cases.each_with_index { |test_case, index| define_preview_test(index, test_case, guard, config.required_previews) }
+        end
+
+        private
+
+        sig { params(index: Integer, test_case: [T.untyped, String, Symbol], guard: Guard, required: T::Array[String]).void }
+        def define_preview_test(index, test_case, guard, required)
+          preview, email, locale = test_case
+          # Index prefix: distinct keys can normalize to the same method name.
+          name = "test_#{index}_#{PreviewRenderer.key(preview, email).gsub(/\W/, '_')}_#{locale}_email_quality"
+          T.unsafe(self).define_method(name) do
+            violations = T.unsafe(self).send(:render_preview_or_skip, preview, email, locale, guard, required)
+            T.unsafe(self).send(:assert_no_quality_violations, violations)
           end
         end
       end
@@ -60,7 +67,13 @@ module ActiveMail
           .returns(T::Array[Guard::Violation])
       end
       def preview_violations(preview, email, locale, guard, around_each)
-        PreviewRenderer.within(preview, email, locale, around_each) { |mail| guard.violations(mail) }
+        config = ActiveMail::Quality.config
+        key = PreviewRenderer.key(preview, email)
+        allowed = config.allow_declined?(key)
+        skip = config.exempt_rules_for(key)
+        PreviewRenderer.within(preview, email, locale, around_each) do |mail|
+          guard.violations(mail, allow_declined: allowed, skip: skip)
+        end
       end
 
       # A non-required preview that can't render is skipped, not a silent pass.

data/lib/activemail/quality/output_filter.rb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module ActiveMail
+  module Quality
+    module OutputFilter
+      class << self
+        extend T::Sig
+
+        sig { params(filter: T.untyped).returns(Proc) }
+        def coerce(filter)
+          return filter if filter.is_a?(Proc)
+
+          pattern, replacement = filter if filter.is_a?(Array) && filter.size == 2
+          raise TypeError, "output filter must be a Proc or [Regexp, String], got #{filter.inspect}" unless pattern.is_a?(Regexp) && replacement.is_a?(String)
+
+          ->(content) { content.gsub(pattern, replacement) }
+        end
+      end
+    end
+  end
+end

data/lib/activemail/quality/render_all.rb

@@ -40,6 +40,7 @@ module ActiveMail
 
       sig { returns(Result) }
       def call
+        @config.check_exemptions!(@config.guard)
         clean_previous_output
         previews = PreviewRenderer.all
         PreviewRenderer.cases(@config, previews).each { |preview, email, locale| render_locale(preview, email, locale) }
@@ -105,10 +106,9 @@ module ActiveMail
       sig { params(preview: T.untyped, email: String, locale: Symbol, label: String).returns(T.nilable(T::Array[Guard::Violation])) }
       def render_one(preview, email, locale, label)
         PreviewRenderer.within(preview, email, locale, @config.around_each) do |mail|
-          next [] if PreviewRenderer.declined?(mail)
-
-          write(preview, email, locale, mail)
-          @config.guard.violations(mail)
+          write(preview, email, locale, mail) unless PreviewRenderer.declined?(mail)
+          key = PreviewRenderer.key(preview, email)
+          @config.guard.violations(mail, allow_declined: @config.allow_declined?(key), skip: @config.exempt_rules_for(key))
         end
       rescue SystemCallError
         raise # disk/permission failures are not template bugs — let them abort the run

data/lib/activemail/quality/rspec.rb

@@ -9,15 +9,17 @@ module ActiveMail
       class ValidEmailMatcher
         extend T::Sig
 
-        sig { params(guard: Guard).void }
-        def initialize(guard: ActiveMail::Quality.guard)
+        sig { params(guard: Guard, allow_declined: T::Boolean, skip: T::Array[Symbol]).void }
+        def initialize(guard: ActiveMail::Quality.guard, allow_declined: false, skip: Guard::NO_SKIP)
           @guard = T.let(guard, Guard)
+          @allow_declined = T.let(allow_declined, T::Boolean)
+          @skip = T.let(skip, T::Array[Symbol])
           @violations = T.let([], T::Array[Guard::Violation])
         end
 
         sig { params(html_or_message: T.untyped).returns(T::Boolean) }
         def matches?(html_or_message)
-          @violations = @guard.violations(html_or_message)
+          @violations = @guard.violations(html_or_message, allow_declined: @allow_declined, skip: @skip)
           @violations.empty?
         end
 
@@ -52,9 +54,12 @@ if defined?(RSpec)
     module Matchers
       extend T::Sig
 
-      sig { params(guard: ActiveMail::Quality::Guard).returns(ActiveMail::Quality::Rspec::ValidEmailMatcher) }
-      def be_a_valid_email(guard: ActiveMail::Quality.guard)
-        ActiveMail::Quality::Rspec::ValidEmailMatcher.new(guard: guard)
+      sig do
+        params(guard: ActiveMail::Quality::Guard, allow_declined: T::Boolean, skip: T::Array[Symbol])
+          .returns(ActiveMail::Quality::Rspec::ValidEmailMatcher)
+      end
+      def be_a_valid_email(guard: ActiveMail::Quality.guard, allow_declined: false, skip: ActiveMail::Quality::Guard::NO_SKIP)
+        ActiveMail::Quality::Rspec::ValidEmailMatcher.new(guard: guard, allow_declined: allow_declined, skip: skip)
       end
     end
   end