activemail 1.2.2 → 2.0.0

data/lib/activemail/quality/guard.rb

@@ -4,127 +4,85 @@
 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])
+      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])
       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
-
-      sig { params(html: String).returns(T::Boolean) }
-      def valid?(html)
-        violations(html).empty?
-      end
-
-      private
-
-      sig { params(rule: Symbol).returns(T::Boolean) }
-      def enabled?(rule)
-        !@disabled.include?(rule)
-      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)
 
-      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?
+        mail = PreviewRenderer.mail(html_or_message)
+        return [] if PreviewRenderer.declined?(mail)
 
-        value
+        html = PreviewRenderer.html_body(mail)
+        (html.empty? ? [] : html_violations(html)) + apply(@message_rules, [mail])
       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
-
-        violations << Violation.new(rule: :max_bytes, message: "HTML is #{html.bytesize} bytes, exceeds #{@max_bytes} (Gmail clipping)")
+      sig { params(html_or_message: T.untyped).returns(T::Boolean) }
+      def valid?(html_or_message)
+        violations(html_or_message).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)
+      private
 
-        errors = doc.errors.reject { |e| e.code == LIBXML_UNKNOWN_TAG_CODE }
-        return if errors.empty?
+      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: :parse_error, message: "malformed HTML: #{errors.first(3).map { |e| e.message.to_s.strip }.join('; ')}")
+        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_table_roles(doc, violations)
-        return unless enabled?(:table_role)
-
-        offenders = doc.css('table').count { |table| table['role'] != 'presentation' }
-        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: :table_role, message: %(#{offenders} <table> missing role="presentation"))
+        rules
       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?
-
-        violations << Violation.new(rule: :img_alt, message: "#{offenders} <img> missing an alt attribute")
+      sig { params(html: String).returns(T::Array[Violation]) }
+      def html_violations(html)
+        apply(@html_rules, [Nokogiri::HTML(html), html])
       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})")
+      sig { params(rules: T::Array[Rule], args: T::Array[T.untyped]).returns(T::Array[Violation]) }
+      def apply(rules, args)
+        rules.flat_map do |rule|
+          rule.messages(args).map { |message| Violation.new(rule: rule.name, message: message) }
         end
-        check_lang(doc, violations)
-      end
-
-      sig { params(doc: Nokogiri::XML::Document, violations: T::Array[Violation]).void }
-      def check_lang(doc, violations)
-        return unless enabled?(:lang)
-
-        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')
       end
     end
   end

data/lib/activemail/quality/minitest.rb

@@ -8,36 +8,34 @@ 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).void }
+      def assert_email_quality(html_or_message, guard: ActiveMail::Quality.guard)
+        assert_no_quality_violations(guard.violations(html_or_message))
       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
+          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)
+          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.
-            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)
+            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
           end
         end
@@ -50,13 +48,31 @@ 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)
+        PreviewRenderer.within(preview, email, locale, around_each) { |mail| guard.violations(mail) }
+      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/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

data/lib/activemail/quality/render_all.rb

@@ -2,8 +2,10 @@
 # frozen_string_literal: true
 
 require 'fileutils'
+require 'pathname'
 
 require_relative '../quality'
+require_relative 'output_dir'
 
 module ActiveMail
   module Quality
@@ -12,6 +14,7 @@ module ActiveMail
       extend T::Sig
 
       class Result < T::Struct
+        const :output_root, Pathname
         const :discovered, Integer
         const :rendered, Integer
         const :render_failures, T::Hash[String, String]
@@ -19,72 +22,125 @@ module ActiveMail
         const :broken_required, T::Array[String]
       end
 
-      sig { params(output_root: T.any(String, Pathname), config: Configuration).void }
-      def initialize(output_root:, config: ActiveMail::Quality.config)
-        @output_root = T.let(Pathname(output_root), Pathname)
+      MARKER = '.activemail_previews'
+      EXTENSIONS = T.let({ html: 'html', text: 'txt' }.freeze, T::Hash[Symbol, String])
+
+      sig { returns(Pathname) }
+      attr_reader :output_root
+
+      sig { params(root: T.any(String, Pathname), config: Configuration).void }
+      def initialize(root:, config: ActiveMail::Quality.config)
         @config = T.let(config, Configuration)
+        @output_root = T.let(OutputDir.resolve(config.output_dir, root), Pathname)
+        @render_failures = T.let({}, T::Hash[String, String])
+        @guard_failures = T.let({}, T::Hash[String, T::Array[Guard::Violation]])
+        @failed_keys = T.let(Set.new, T::Set[String])
+        @rendered = T.let(0, Integer)
       end
 
       sig { returns(Result) }
       def call
-        FileUtils.rm_rf(@output_root)
-        FileUtils.mkdir_p(@output_root)
-
-        render_failures = {}
-        guard_failures = {}
+        clean_previous_output
         previews = PreviewRenderer.all
-        rendered = render_all(previews, render_failures, guard_failures)
+        PreviewRenderer.cases(@config, previews).each { |preview, email, locale| render_locale(preview, email, locale) }
 
         Result.new(
-          discovered: previews.size, rendered: rendered, render_failures: render_failures,
-          guard_failures: guard_failures, broken_required: broken_required(previews, render_failures, guard_failures)
+          output_root: @output_root, discovered: previews.size, rendered: @rendered, render_failures: @render_failures,
+          guard_failures: @guard_failures, broken_required: broken_required(previews)
         )
       end
 
       private
 
-      # A required preview that fails, OR is never discovered at all (typo / deleted), is broken.
-      sig do
-        params(
-          previews: T::Array[[T.untyped, String]],
-          render_failures: T::Hash[String, String],
-          guard_failures: T::Hash[String, T::Array[Guard::Violation]]
-        ).returns(T::Array[String])
+      sig { void }
+      def clean_previous_output
+        ensure_owned!
+        @output_root.glob('**/*.{html,txt}').each { |path| path.delete if path.file? }
+        prune_empty_directories
+        FileUtils.mkdir_p(@output_root)
+        FileUtils.touch(@output_root.join(MARKER))
       end
-      def broken_required(previews, render_failures, guard_failures)
+
+      # The marker proves a previous run owns the directory: without it, an existing
+      # non-empty output_dir (public/, app/...) is never touched.
+      sig { void }
+      def ensure_owned!
+        return if !@output_root.exist? || @output_root.join(MARKER).exist? || @output_root.empty?
+
+        raise ArgumentError, "output_dir #{@output_root} is not empty and was not created by activemail (no #{MARKER}); use a dedicated directory"
+      end
+
+      sig { void }
+      def prune_empty_directories
+        @output_root.glob('**/*/').sort_by { |dir| -dir.to_s.size }.each { |dir| dir.rmdir if dir.empty? }
+      end
+
+      # A required preview that fails, OR is never discovered at all (typo / deleted), is broken.
+      sig { params(previews: T::Array[[T.untyped, String]]).returns(T::Array[String]) }
+      def broken_required(previews)
         required = @config.required_previews
         discovered = previews.map { |preview, email| PreviewRenderer.key(preview, email) }
-        ((render_failures.keys | guard_failures.keys) & required) | (required - discovered)
+        (@failed_keys.to_a & required) | (required - discovered)
       end
 
-      sig do
-        params(previews: T::Array[[T.untyped, String]], render_failures: T::Hash[String, String], guard_failures: T::Hash[String, T::Array[Guard::Violation]]).returns(Integer)
-      end
-      def render_all(previews, render_failures, guard_failures)
-        previews.count do |preview, email|
-          key = PreviewRenderer.key(preview, email)
-          path = render_one(preview, email, render_failures, key)
-          next false unless path
-
-          violations = @config.guard.violations(File.read(path))
-          guard_failures[key] = violations unless violations.empty?
-          true
-        end
+      sig { params(preview: T.untyped, email: String, locale: Symbol).void }
+      def render_locale(preview, email, locale)
+        key = PreviewRenderer.key(preview, email)
+        label = locale == I18n.default_locale ? key : "#{key} [#{locale}]"
+        violations = render_one(preview, email, locale, label)
+        record(key, label, violations)
       end
 
-      sig do
-        params(preview: T.untyped, email: String, failures: T::Hash[String, String], key: String).returns(T.nilable(Pathname))
+      sig { params(key: String, label: String, violations: T.nilable(T::Array[Guard::Violation])).void }
+      def record(key, label, violations)
+        return @failed_keys << key if violations.nil?
+
+        @rendered += 1
+        return if violations.empty?
+
+        @failed_keys << key
+        @guard_failures[label] = violations
       end
-      def render_one(preview, email, failures, key)
-        PreviewRenderer.render_to_disk(preview, email, @output_root)
+
+      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)
+        end
       rescue SystemCallError
         raise # disk/permission failures are not template bugs — let them abort the run
       rescue StandardError => e
-        root = e.cause
-        cause = root ? "\n  caused by: #{root.class}: #{root.message}" : ''
-        failures[key] = "#{e.class}: #{e.message}\n  #{e.backtrace&.first(5)&.join("\n  ")}#{cause}"
+        @render_failures[label] = describe(e)
         nil
       end
+
+      sig { params(error: StandardError).returns(String) }
+      def describe(error)
+        root = error.cause
+        cause = root ? "\n  caused by: #{root.class}: #{root.message}" : ''
+        "#{error.class}: #{error.message}\n  #{error.backtrace&.first(5)&.join("\n  ")}#{cause}"
+      end
+
+      sig { params(preview: T.untyped, email: String, locale: Symbol, mail: T.untyped).void }
+      def write(preview, email, locale, mail)
+        dir = @output_root.join(preview.preview_name)
+        FileUtils.mkdir_p(dir)
+        # The default locale stays unsuffixed so a diff against an older run still lines up.
+        stem = locale == I18n.default_locale ? email : "#{email}.#{locale}"
+        contents = { html: PreviewRenderer.html_body(mail), text: PreviewRenderer.text_body(mail) }
+
+        @config.formats.each do |format|
+          File.write(dir.join("#{stem}.#{EXTENSIONS.fetch(format)}"), filtered(contents.fetch(format)))
+        end
+      end
+
+      sig { params(content: String).returns(String) }
+      def filtered(content)
+        @config.output_filters.reduce(content) { |acc, filter| filter.call(acc) }
+      end
     end
   end
 end

data/lib/activemail/quality/rspec.rb

@@ -6,8 +6,6 @@ require_relative '../quality'
 module ActiveMail
   module Quality
     module Rspec
-      # Standalone matcher object — testable without booting RSpec. The
-      # be_a_valid_email helper below just returns it (no RSpec::Matchers.define DSL).
       class ValidEmailMatcher
         extend T::Sig
 
@@ -17,9 +15,9 @@ module ActiveMail
           @violations = T.let([], T::Array[Guard::Violation])
         end
 
-        sig { params(html: String).returns(T::Boolean) }
-        def matches?(html)
-          @violations = @guard.violations(html)
+        sig { params(html_or_message: T.untyped).returns(T::Boolean) }
+        def matches?(html_or_message)
+          @violations = @guard.violations(html_or_message)
           @violations.empty?
         end
 
@@ -42,7 +40,7 @@ module ActiveMail
 
         sig { returns(String) }
         def formatted_violations
-          @violations.map { |v| "  - [#{v.rule}] #{v.message}" }.join("\n")
+          @violations.map { |v| "  - #{v}" }.join("\n")
         end
       end
     end
@@ -50,8 +48,6 @@ module ActiveMail
 end
 
 if defined?(RSpec)
-  # ValidEmailMatcher already implements the full matcher protocol, so a simple
-  # helper returning it is enough — no RSpec::Matchers.define DSL needed.
   module RSpec
     module Matchers
       extend T::Sig