activemail 1.2.3 → 2.1.0

data/lib/activemail/quality/guard.rb

@@ -4,127 +4,105 @@
 require 'nokogiri'
 require 'sorbet-runtime'
 
-require_relative '../libxml'
+require_relative 'builtin_rules'
+require_relative 'preview_renderer'
+require_relative 'rule'
 
 module ActiveMail
   module Quality
     class Guard
       extend T::Sig
 
-      # One failed invariant. :rule is a stable symbol for programmatic matching;
-      # :message is human-facing.
       class Violation < T::Struct
+        extend T::Sig
+
         const :rule, Symbol
         const :message, String
+
+        sig { returns(String) }
+        def to_s
+          "[#{rule}] #{message}"
+        end
       end
 
-      DISABLEABLE = T.let(%i[max_bytes parse_error table_role img_alt lang min_full_doc_bytes].freeze, T::Array[Symbol])
+      DISABLEABLE = BuiltinRules::NAMES
       # Gmail clips messages past ~102KB.
       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
-
-      # disable: any subset of DISABLEABLE to skip those checks.
-      sig { params(max_bytes: Integer, min_full_doc_bytes: Integer, disable: T::Array[Symbol]).void }
-      def initialize(max_bytes: DEFAULT_MAX_BYTES, min_full_doc_bytes: DEFAULT_MIN_FULL_DOC_BYTES, disable: [])
-        # A non-positive threshold would silently disable (or invert) a check.
-        @max_bytes = T.let(positive_threshold!(:max_bytes, max_bytes), Integer)
-        @min_full_doc_bytes = T.let(positive_threshold!(:min_full_doc_bytes, min_full_doc_bytes), Integer)
-        unknown = disable - DISABLEABLE
-        raise ArgumentError, "unknown rule(s): #{unknown.inspect}, expected a subset of #{DISABLEABLE.inspect}" unless unknown.empty?
-
-        @disabled = T.let(disable.to_set, T::Set[Symbol])
+      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
 
-      sig { params(html: String).returns(T::Array[Violation]) }
-      def violations(html)
-        violations = []
-        check_size(html, violations)
-
-        doc = Nokogiri::HTML(html)
-        check_well_formed(doc, violations)
-        check_table_roles(doc, violations)
-        check_img_alts(doc, violations)
-        check_full_document(html, doc, violations) if ::ActiveMail.full_document?(html)
-        violations
-      end
+      # 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)
 
-      sig { params(html: String).returns(T::Boolean) }
-      def valid?(html)
-        violations(html).empty?
-      end
-
-      private
+        mail = PreviewRenderer.mail(html_or_message)
+        return declined_violations(allow_declined) if PreviewRenderer.declined?(mail)
 
-      sig { params(rule: Symbol).returns(T::Boolean) }
-      def enabled?(rule)
-        !@disabled.include?(rule)
+        html = PreviewRenderer.html_body(mail)
+        (html.empty? ? [] : html_violations(html, skip)) + apply(@message_rules, [mail], skip)
       end
 
-      sig { params(name: Symbol, value: Integer).returns(Integer) }
-      def positive_threshold!(name, value)
-        raise ArgumentError, "#{name} must be a positive integer, got #{value}" unless value.positive?
-
-        value
+      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(html: String, violations: T::Array[Violation]).void }
-      def check_size(html, violations)
-        return unless enabled?(:max_bytes)
-        return if html.bytesize <= @max_bytes
+      sig { params(skip: T::Array[Symbol]).void }
+      def check_skippable!(skip)
+        return if skip.empty?
 
-        violations << Violation.new(rule: :max_bytes, message: "HTML is #{html.bytesize} bytes, exceeds #{@max_bytes} (Gmail clipping)")
+        unknown = skip - @rule_names
+        raise ArgumentError, "unknown rule(s) to skip: #{unknown.inspect}, expected a subset of #{@rule_names.inspect}" unless unknown.empty?
       end
 
-      # The Core surfaces libxml2 repairs on input; the validation layer must not
-      # silently bless malformed *output* (mismatched tags, bad entities) before send.
-      sig { params(doc: Nokogiri::XML::Document, violations: T::Array[Violation]).void }
-      def check_well_formed(doc, violations)
-        return unless enabled?(:parse_error)
-
-        errors = doc.errors.reject { |e| e.code == LIBXML_UNKNOWN_TAG_CODE }
-        return if errors.empty?
+      private
 
-        violations << Violation.new(rule: :parse_error, message: "malformed HTML: #{errors.first(3).map { |e| e.message.to_s.strip }.join('; ')}")
+      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(doc: Nokogiri::XML::Document, violations: T::Array[Violation]).void }
-      def check_table_roles(doc, violations)
-        return unless enabled?(:table_role)
-
-        offenders = doc.css('table').count { |table| table['role'] != 'presentation' }
-        return if offenders.zero?
+      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
+        raise ArgumentError, "unknown rule(s): #{unknown.inspect}, expected a subset of #{DISABLEABLE.inspect}" unless unknown.empty?
 
-        violations << Violation.new(rule: :table_role, message: %(#{offenders} <table> missing role="presentation"))
+        unique_names!(builtin.rules.reject { |rule| disable.include?(rule.name) } + custom)
       end
 
-      sig { params(doc: Nokogiri::XML::Document, violations: T::Array[Violation]).void }
-      def check_img_alts(doc, violations)
-        return unless enabled?(:img_alt)
-
-        offenders = doc.css('img').count { |img| !img.key?('alt') }
-        return if offenders.zero?
+      sig { params(rules: T::Array[Rule]).returns(T::Array[Rule]) }
+      def unique_names!(rules)
+        duplicates = rules.map(&:name).tally.select { |_name, count| count > 1 }.keys
+        raise ArgumentError, "duplicate rule name(s): #{duplicates.inspect}" unless duplicates.empty?
 
-        violations << Violation.new(rule: :img_alt, message: "#{offenders} <img> missing an alt attribute")
+        rules
       end
 
-      sig { params(html: String, doc: Nokogiri::XML::Document, violations: T::Array[Violation]).void }
-      def check_full_document(html, doc, violations)
-        if enabled?(:min_full_doc_bytes) && html.bytesize < @min_full_doc_bytes
-          violations << Violation.new(rule: :min_full_doc_bytes, message: "full document is only #{html.bytesize} bytes (under #{@min_full_doc_bytes})")
-        end
-        check_lang(doc, violations)
+      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(doc: Nokogiri::XML::Document, violations: T::Array[Violation]).void }
-      def check_lang(doc, violations)
-        return unless enabled?(:lang)
+      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)
 
-        html_tag = doc.at_css('html')
-        lang = html_tag && html_tag['lang']
-        return if lang && !lang.strip.empty?
-
-        violations << Violation.new(rule: :lang, message: '<html> must declare a non-blank lang attribute')
+          rule.messages(args).map { |message| Violation.new(rule: rule.name, message: message) }
+        end
       end
     end
   end

data/lib/activemail/quality/minitest.rb

@@ -8,37 +8,42 @@ module ActiveMail
     module Minitest
       extend T::Sig
 
-      sig { params(html: String, guard: Guard).void }
-      def assert_email_quality(html, guard: ActiveMail::Quality.guard)
-        violations = guard.violations(html)
-        # assert is injected by the host's Minitest test class.
-        T.unsafe(self).assert violations.empty?,
-                              "email quality violations:\n#{violations.map { |v| "  - [#{v.rule}] #{v.message}" }.join("\n")}"
+      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 { params(preview: T.untyped, email: String, guard: Guard).void }
-      def assert_preview_quality(preview, email, guard: ActiveMail::Quality.guard)
-        assert_email_quality(PreviewRenderer.render(preview, email), guard: guard)
+      sig do
+        params(preview: T.untyped, email: String, guard: Guard, locale: Symbol, around_each: T.nilable(Proc)).void
+      end
+      def assert_preview_quality(preview, email, guard: ActiveMail::Quality.guard, locale: I18n.default_locale,
+                                 around_each: ActiveMail::Quality.config.around_each)
+        assert_no_quality_violations(preview_violations(preview, email, locale, guard, around_each))
       end
 
       module ClassMethods
         extend T::Sig
 
-        # One test per discovered preview; a non-required preview that can't render
-        # is skipped, a required one fails (see #render_preview_or_skip).
         sig { params(guard: Guard).void }
         def assert_quality_for_all_previews(guard: ActiveMail::Quality.guard)
-          required = ActiveMail::Quality.config.required_previews
-          previews = PreviewRenderer.all
+          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 previews.empty?
-          previews.each_with_index do |(preview, email), i|
-            key = PreviewRenderer.key(preview, email)
-            # Index prefix: distinct keys can normalize to the same method name.
-            T.unsafe(self).define_method("test_#{i}_#{key.gsub(/\W/, '_')}_email_quality") do
-              html = T.unsafe(self).send(:render_preview_or_skip, preview, email, key, required)
-              T.unsafe(self).assert_email_quality(html, guard: guard)
-            end
+          Kernel.warn('[activemail] assert_quality_for_all_previews: no previews discovered.') if cases.empty?
+          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
@@ -50,13 +55,37 @@ module ActiveMail
 
       private
 
-      # Returns rendered HTML; a non-required preview that fails is skipped (not a
-      # silent pass), a required one fails. flunk/skip are injected by Minitest; both raise.
-      sig { params(preview: T.untyped, email: String, key: String, required: T::Array[String]).returns(String) }
-      def render_preview_or_skip(preview, email, key, required)
-        PreviewRenderer.render(preview, email)
+      sig { params(violations: T::Array[Guard::Violation]).void }
+      def assert_no_quality_violations(violations)
+        # assert is injected by the host's Minitest test class.
+        T.unsafe(self).assert violations.empty?,
+                              "email quality violations:\n#{violations.map { |v| "  - #{v}" }.join("\n")}"
+      end
+
+      sig do
+        params(preview: T.untyped, email: String, locale: Symbol, guard: Guard, around_each: T.nilable(Proc))
+          .returns(T::Array[Guard::Violation])
+      end
+      def preview_violations(preview, email, locale, guard, around_each)
+        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.
+      sig do
+        params(preview: T.untyped, email: String, locale: Symbol, guard: Guard, required: T::Array[String])
+          .returns(T::Array[Guard::Violation])
+      end
+      def render_preview_or_skip(preview, email, locale, guard, required)
+        preview_violations(preview, email, locale, guard, ActiveMail::Quality.config.around_each)
       rescue StandardError => e
-        msg = "#{key} did not render (#{e.class}: #{e.message})"
+        key = PreviewRenderer.key(preview, email)
+        msg = "#{key} [#{locale}] did not render (#{e.class}: #{e.message})"
         required.include?(key) ? T.unsafe(self).flunk("required preview #{msg}") : T.unsafe(self).skip(msg)
       end
     end

data/lib/activemail/quality/output_dir.rb

@@ -0,0 +1,52 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'pathname'
+require 'sorbet-runtime'
+
+module ActiveMail
+  module Quality
+    # RenderAll deletes inside this directory, so it must not escape the host root.
+    module OutputDir
+      class << self
+        extend T::Sig
+
+        sig { params(value: String).returns(String) }
+        def validate!(value)
+          raise ArgumentError, 'output_dir must not be blank' if value.strip.empty?
+          raise ArgumentError, "output_dir must be relative, got #{value.inspect}" if Pathname(value).absolute?
+
+          segments = value.split(%r{[/\\]}).reject(&:empty?)
+          raise ArgumentError, "output_dir must not contain '..', got #{value.inspect}" if segments.include?('..')
+          raise ArgumentError, "output_dir must not be '.', got #{value.inspect}" if segments.all?('.')
+
+          value
+        end
+
+        sig { params(value: String, root: T.any(String, Pathname)).returns(Pathname) }
+        def resolve(value, root)
+          validate!(value)
+          base = real(root.to_s)
+          resolved = real(File.expand_path(value, base.to_s))
+          raise ArgumentError, "output_dir #{value.inspect} must resolve strictly under #{base}" unless resolved.to_s.start_with?("#{base}/")
+
+          resolved
+        end
+
+        private
+
+        # Symlinks are resolved on the deepest existing ancestor, so a link cannot smuggle the target out.
+        sig { params(path: String).returns(Pathname) }
+        def real(path)
+          missing = []
+          existing = Pathname(File.expand_path(path))
+          until existing.exist?
+            missing.unshift(existing.basename)
+            existing = existing.dirname
+          end
+          missing.reduce(existing.realpath) { |acc, segment| acc.join(segment) }
+        end
+      end
+    end
+  end
+end

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/preview_renderer.rb

@@ -1,8 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
-require 'fileutils'
-require 'pathname'
+require 'i18n'
 require 'sorbet-runtime'
 
 module ActiveMail
@@ -11,29 +10,29 @@ module ActiveMail
       class << self
         extend T::Sig
 
-        # preview and message are external/dynamic ActionMailer & Mail objects.
-        sig { params(preview: T.untyped, email: String).returns(String) }
-        def render(preview, email)
-          html_body(preview.call(email))
-        end
-
-        # The single source for the "preview_name#email" key format (config keys,
-        # render_all, the Minitest helper).
         sig { params(preview: T.untyped, email: String).returns(String) }
         def key(preview, email)
           "#{preview.preview_name}##{email}"
         end
 
-        sig { params(preview: T.untyped, email: String, output_root: T.any(String, Pathname)).returns(Pathname) }
-        def render_to_disk(preview, email, output_root)
-          dir = Pathname(output_root).join(preview.preview_name)
-          FileUtils.mkdir_p(dir)
-          path = dir.join("#{email}.html")
-          File.write(path, render(preview, email))
-          path
+        # The message renders lazily: every read of it must happen inside the block.
+        sig do
+          params(preview: T.untyped, email: String, locale: Symbol, around_each: T.nilable(Proc), block: T.proc.params(mail: T.untyped).returns(T.untyped))
+            .returns(T.untyped)
+        end
+        def within(preview, email, locale, around_each, &block)
+          ran = T.let(false, T::Boolean)
+          result = T.let(nil, T.untyped)
+          run = lambda do
+            ran = true
+            result = I18n.with_locale(locale) { block.call(mail(preview.call(email, locale: locale))) }
+          end
+          around_each ? around_each.call(preview, email, locale, &run) : run.call
+          raise ArgumentError, 'around_each must yield' unless ran
+
+          result
         end
 
-        # [] when ActionMailer previews aren't loaded (host has none / previews disabled).
         sig { returns(T::Array[[T.untyped, String]]) }
         def all
           return [] unless defined?(ActionMailer::Preview)
@@ -43,26 +42,40 @@ module ActiveMail
           end
         end
 
-        # Returns '' for a plain-text-only message so the Guard surfaces missing
-        # HTML instead of validating plain text as if it were HTML.
-        sig { params(message: T.untyped).returns(String) }
-        def html_body(message)
-          mail = message.respond_to?(:message) ? message.message : message
-          body = mail.html_part&.body || single_part_html_body(mail)
-          return '' unless body
+        # '' for a plain-text-only message: plain text must not be validated as HTML.
+        sig { params(mail: T.untyped).returns(String) }
+        def html_body(mail)
+          body_of(mail, mail.html_part, [nil, 'text/html'])
+        end
+
+        sig { params(mail: T.untyped).returns(String) }
+        def text_body(mail)
+          body_of(mail, mail.text_part, ['text/plain'])
+        end
 
-          body.respond_to?(:decoded) ? body.decoded : body.to_s
+        # NullMail answers every respond_to? and returns nil: it is its own message.
+        sig { params(message: T.untyped).returns(T.untyped) }
+        def mail(message)
+          (message.message if message.respond_to?(:message)) || message
         end
 
-        private
+        sig { params(mail: T.untyped).returns(T::Boolean) }
+        def declined?(mail)
+          mail.class.name.to_s.end_with?('::NullMail')
+        end
 
-        # A single-part body counts as HTML only when its content-type says so
-        # (or is unset); a declared text/plain body is not HTML.
-        sig { params(mail: T.untyped).returns(T.untyped) }
-        def single_part_html_body(mail)
-          return if mail.multipart?
+        sig { params(config: Configuration, previews: T::Array[[T.untyped, String]]).returns(T::Array[[T.untyped, String, Symbol]]) }
+        def cases(config, previews = all)
+          previews.flat_map { |preview, email| config.locales_for(preview).map { |locale| [preview, email, locale] } }
+        end
+
+        private
 
-          mail.body if mail.mime_type.nil? || mail.mime_type == 'text/html'
+        # A single-part body counts only when its content-type says so (unset counts as HTML).
+        sig { params(mail: T.untyped, part: T.untyped, mime_types: T::Array[T.nilable(String)]).returns(String) }
+        def body_of(mail, part, mime_types)
+          body = part&.body || (mail.body if !mail.multipart? && mime_types.include?(mail.mime_type))
+          body ? body.decoded : ''
         end
       end
     end