activemail 1.0.0

data/lib/active_mail/tokens.rb

@@ -0,0 +1,139 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module ActiveMail
+  # Design-tokens registry: the single Ruby source of truth, bridged to SCSS by #to_scss.
+  class Tokens
+    extend T::Sig
+
+    TokenMap = T.type_alias { T::Hash[Symbol, String] }
+
+    DEFAULT_COLORS = T.let(
+      {
+        primary: '#2a9d8f',
+        secondary: '#264653',
+        text: '#1a1a1a',
+        background: '#ffffff',
+        muted: '#6b7280',
+        border: '#e5e7eb',
+        button_text: '#ffffff'
+      }.freeze,
+      TokenMap
+    )
+
+    SYSTEM_FONT_STACK = '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif'
+
+    DEFAULT_FONTS = T.let(
+      {
+        body: SYSTEM_FONT_STACK,
+        heading: SYSTEM_FONT_STACK
+      }.freeze,
+      TokenMap
+    )
+
+    DEFAULT_SPACINGS = T.let(
+      {
+        xs: '4px',
+        sm: '8px',
+        md: '16px',
+        lg: '24px',
+        xl: '40px'
+      }.freeze,
+      TokenMap
+    )
+
+    sig { void }
+    def initialize
+      @colors = T.let(DEFAULT_COLORS.dup, TokenMap)
+      @fonts = T.let(DEFAULT_FONTS.dup, TokenMap)
+      @spacings = T.let(DEFAULT_SPACINGS.dup, TokenMap)
+    end
+
+    # value given → set, omitted → get. Open registry: any key is accepted (define
+    # custom tokens for custom components); color!/font!/spacing! fail loud on read.
+    sig { params(name: T.any(String, Symbol), value: T.nilable(String)).returns(T.nilable(String)) }
+    def color(name, value = nil)
+      access(@colors, name, value)
+    end
+
+    sig { params(name: T.any(String, Symbol), value: T.nilable(String)).returns(T.nilable(String)) }
+    def font(name, value = nil)
+      access(@fonts, name, value)
+    end
+
+    sig { params(name: T.any(String, Symbol), value: T.nilable(String)).returns(T.nilable(String)) }
+    def spacing(name, value = nil)
+      access(@spacings, name, value)
+    end
+
+    # Strict reads for code that must have the token (e.g. a component's inline
+    # color): raise rather than interpolating nil into the CSS.
+    sig { params(name: T.any(String, Symbol)).returns(String) }
+    def color!(name)
+      fetch!(@colors, :color, name)
+    end
+
+    sig { params(name: T.any(String, Symbol)).returns(String) }
+    def font!(name)
+      fetch!(@fonts, :font, name)
+    end
+
+    sig { params(name: T.any(String, Symbol)).returns(String) }
+    def spacing!(name)
+      fetch!(@spacings, :spacing, name)
+    end
+
+    # Frozen dup: mutating the returned hash must not bypass the DSL setters.
+    sig { returns(TokenMap) }
+    def colors
+      @colors.dup.freeze
+    end
+
+    sig { returns(TokenMap) }
+    def fonts
+      @fonts.dup.freeze
+    end
+
+    sig { returns(TokenMap) }
+    def spacings
+      @spacings.dup.freeze
+    end
+
+    # SCSS bridge: !default lets power-users pre-declare overrides upstream.
+    # Values are emitted verbatim (trusted, app-controlled input) — not escaped.
+    sig { returns(String) }
+    def to_scss
+      lines = scss_lines('color', @colors) + scss_lines('font', @fonts) + scss_lines('spacing', @spacings)
+      "#{lines.join("\n")}\n"
+    end
+
+    private
+
+    sig { params(store: TokenMap, kind: Symbol, name: T.any(String, Symbol)).returns(String) }
+    def fetch!(store, kind, name)
+      store.fetch(name.to_sym) { raise KeyError, "unknown #{kind} token #{name.inspect}" }
+    end
+
+    sig { params(store: TokenMap, name: T.any(String, Symbol), value: T.nilable(String)).returns(T.nilable(String)) }
+    def access(store, name, value)
+      key = name.to_sym
+      return store[key] if value.nil?
+      # Emitted verbatim into SCSS by #to_scss — reject blanks that would yield broken CSS.
+      raise ArgumentError, "token #{key} value must not be blank" if value.strip.empty?
+
+      store[key] = value
+    end
+
+    sig { params(group: String, store: TokenMap).returns(T::Array[String]) }
+    def scss_lines(group, store)
+      store.map { |name, value| "$am-#{group}-#{scss_name(name)}: #{value} !default;" }
+    end
+
+    sig { params(name: Symbol).returns(String) }
+    def scss_name(name)
+      name.to_s.tr('_', '-')
+    end
+  end
+end

data/lib/active_mail/version.rb

@@ -0,0 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ActiveMail
+  VERSION = '1.0.0'
+end

data/lib/active_mail.rb

@@ -0,0 +1,161 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'sorbet-runtime'
+
+require_relative 'active_mail/version'
+require_relative 'active_mail/components/base'
+require_relative 'active_mail/components/button'
+require_relative 'active_mail/components/row'
+require_relative 'active_mail/components/columns'
+require_relative 'active_mail/components/container'
+require_relative 'active_mail/components/inky'
+require_relative 'active_mail/components/block_grid'
+require_relative 'active_mail/components/menu'
+require_relative 'active_mail/components/menu_item'
+require_relative 'active_mail/components/center'
+require_relative 'active_mail/components/callout'
+require_relative 'active_mail/components/spacer'
+require_relative 'active_mail/components/h_line'
+require_relative 'active_mail/components/wrapper'
+require_relative 'active_mail/components/cta'
+require_relative 'active_mail/components/info_box'
+require_relative 'active_mail/configuration'
+require_relative 'active_mail/inliner/interceptor'
+require_relative 'active_mail/parse_error_reporter'
+
+module ActiveMail
+  class ParseError < StandardError; end
+
+  class Core
+    extend T::Sig
+
+    # Nokogiri cannot parse a bare <th> outside a <tr>; components that emit
+    # <th> use this placeholder, swapped back at the end.
+    INTERIM_TH_TAG = 'active-mail-interim-th'
+    INTERIM_TH_TAG_REGEX = T.let(%r{(?<=<|</)#{Regexp.escape(INTERIM_TH_TAG)}}, Regexp)
+
+    DEFAULT_COMPONENTS = T.let(
+      {
+        'button' => ActiveMail::Components::Button,
+        'row' => ActiveMail::Components::Row,
+        'columns' => ActiveMail::Components::Columns,
+        'container' => ActiveMail::Components::Container,
+        'inky' => ActiveMail::Components::Inky,
+        'block-grid' => ActiveMail::Components::BlockGrid,
+        'menu' => ActiveMail::Components::Menu,
+        'item' => ActiveMail::Components::MenuItem,
+        'center' => ActiveMail::Components::Center,
+        'callout' => ActiveMail::Components::Callout,
+        'spacer' => ActiveMail::Components::Spacer,
+        'h-line' => ActiveMail::Components::HLine,
+        'wrapper' => ActiveMail::Components::Wrapper
+      }.freeze,
+      ActiveMail::ComponentMap
+    )
+
+    sig { returns(Integer) }
+    attr_reader :column_count, :container_width
+
+    sig { returns(T::Hash[String, ActiveMail::Components::Base]) }
+    attr_reader :component_instances
+
+    sig { params(options: T::Hash[Symbol, T.untyped]).void }
+    def initialize(options = {})
+      config = ::ActiveMail.configuration
+      @component_instances = T.let(build_components(config, options[:components]), T::Hash[String, ActiveMail::Components::Base])
+      @column_count = T.let(ActiveMail.assert_positive_dimension!(:column_count, options[:column_count] || config.column_count), Integer)
+      @container_width = T.let(ActiveMail.assert_positive_dimension!(:container_width, options[:container_width] || config.container_width), Integer)
+    end
+
+    # Object, not String: ActionView::OutputBuffer is no longer a String since Rails 7.1.
+    sig { params(html_string: Object).returns(String) }
+    def release_the_kraken(html_string)
+      raws, str = extract_raws(normalize_input(html_string))
+      parse_cmd = ::ActiveMail.full_document?(str) ? :parse : :fragment
+      html = Nokogiri::HTML.public_send(parse_cmd, str)
+      ParseErrorReporter.new(component_instances.keys).call(html.errors)
+      transform_doc(html)
+      string = html.to_html
+      string = string.gsub(INTERIM_TH_TAG_REGEX, 'th')
+      # Needle is a literal U+00A0 (Nokogiri decodes the nbsp entity to one); re-encode
+      # it to the entity for email clients that mishandle raw NBSP bytes.
+      string = string.gsub(' ', '&nbsp;')
+      re_inject_raws(string, raws)
+    end
+
+    sig { params(elem: Nokogiri::XML::Node).returns(Nokogiri::XML::Node) }
+    def transform_doc(elem)
+      if elem.respond_to?(:children)
+        elem.children.each { |child| transform_doc(child) }
+        markup = component_factory(elem)
+        elem.replace(markup) if markup
+      end
+      elem
+    end
+
+    sig { params(node: Nokogiri::XML::Node).returns(T.nilable(String)) }
+    def component_factory(node)
+      component = component_instances[node.name]
+      return unless component
+
+      # Nokogiri::NodeSet has no #join; map to String first.
+      inner = node.children.map(&:to_s).join # rubocop:disable Style/MapJoin
+      component.transform(node, inner)
+    end
+
+    sig { params(string: String).returns([T::Array[String], String]) }
+    def extract_raws(string)
+      raws = []
+      i = 0
+      # Only the tags + content, across lines: surrounding whitespace is left in
+      # place (true pass-through; eating adjacent newlines corrupts <pre>/inline text).
+      regex = %r{< *raw *>([\s\S]*?)</ *raw *>}i
+      str = string
+      while (raw = str.match(regex))
+        raws[i] = T.must(raw[1])
+        str = str.sub(regex, "###RAW#{i}###")
+        i += 1
+      end
+      [raws, str]
+    end
+
+    sig { params(string: String, raws: T::Array[String]).returns(String) }
+    def re_inject_raws(string, raws)
+      str = string
+      raws.each_with_index do |val, i|
+        # Block form: the 2-arg String#sub would expand \0/\1/\& in val.
+        str = str.sub("###RAW#{i}###") { val }
+      end
+      str = str.html_safe if str.respond_to?(:html_safe)
+      str
+    end
+
+    private
+
+    # Internal transpilation details, not public surface (column_count/container_width stay public).
+    private :component_instances, :transform_doc, :component_factory, :extract_raws, :re_inject_raws
+
+    sig { params(config: ActiveMail::Configuration, overrides: T.untyped).returns(T::Hash[String, ActiveMail::Components::Base]) }
+    def build_components(config, overrides)
+      # Lookup is by node name (String); a Symbol key would never match.
+      overrides = (overrides || {}).transform_keys(&:to_s)
+      overrides.each { |tag, klass| ActiveMail::Components.validate_component!(tag, klass) }
+      DEFAULT_COMPONENTS.merge(config.components).merge(overrides).transform_values { |klass| klass.new(self) }
+    end
+
+    sig { params(html_string: Object).returns(String) }
+    def normalize_input(html_string)
+      html_string = html_string.to_s
+      html_string = html_string.dup.force_encoding(Encoding::UTF_8) if html_string.encoding == Encoding::BINARY
+      html_string = ::ActiveMail.scrub_invalid_bytes(html_string) unless html_string.valid_encoding?
+      html_string.gsub(/doctype/i, 'DOCTYPE')
+    end
+  end
+end
+
+if defined?(Rails::Engine)
+  require 'active_mail/rails/engine'
+  require 'active_mail/rails/template_handler'
+end

data/lib/activemail.rb

@@ -0,0 +1,5 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Bundler auto-requires the gem name ('activemail'); the library lives in 'active_mail'.
+require 'active_mail'

data/lib/generators/active_mail/component_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/named_base'
+
+module ActiveMail
+  module Generators
+    class ComponentGenerator < ::Rails::Generators::NamedBase
+      desc 'Scaffold an ActiveMail component class (rails g active_mail:component Cta)'
+      source_root File.join(File.dirname(__FILE__), 'templates')
+
+      def create_component
+        template 'component.rb.tt', File.join('app', 'mailers', 'components', "#{file_name}.rb")
+      end
+
+      def show_register_snippet
+        say "\nRegister the component in config/initializers/active_mail.rb:", :green
+        say %(  config.register_component "#{tag_name}", Components::#{class_name})
+        say '(top-level Components:: — rename the module if it collides in your app)', :yellow
+        say "\nThen use <#{tag_name}>…</#{tag_name}> in your ActiveMail views.\n"
+      end
+
+      private
+
+      # Tag = kebab-cased class name, matching the gem's component naming.
+      def tag_name
+        file_name.tr('_', '-')
+      end
+    end
+  end
+end

data/lib/generators/active_mail/install_generator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module ActiveMail
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      desc 'Install ActiveMail: initializer and a mailer layout'
+      source_root File.join(File.dirname(__FILE__), 'templates')
+      argument :layout_name, type: :string, default: 'mailer', banner: 'layout_name'
+
+      class_option :haml, desc: 'Generate the layout in Haml', type: :boolean
+      class_option :slim, desc: 'Generate the layout in Slim', type: :boolean
+
+      def create_initializer
+        template 'initializer.rb', File.join('config', 'initializers', 'active_mail.rb')
+      end
+
+      # A plain mailer.html.erb would win over the generated inky layout; keep it.
+      def preserve_original_mailer_layout
+        return unless layout_name == 'mailer' && extension == 'erb'
+
+        original = File.join(layouts_base_dir, 'mailer.html.erb')
+        back_up_layout(original) if File.exist?(File.join(destination_root, original))
+      end
+
+      def create_mailer_layout
+        template "mailer_layout.html.inky-#{extension}",
+                 File.join(layouts_base_dir, "#{layout_name.underscore}.html.inky-#{extension}")
+      end
+
+      def show_readme
+        say "\nActiveMail installed.", :green
+        say '  • config/initializers/active_mail.rb — configure tokens, inliner, components.'
+        say "  • app/views/layouts/#{layout_name.underscore}.html.inky-#{extension} — your mailer layout."
+        say "\nPoint your mailers at the layout, e.g. `layout \"#{layout_name.underscore}\"`, and"
+        say "name views *.html.inky-#{extension} to enable ActiveMail markup."
+        say "\nCustomize styling via Ruby tokens in the initializer (config.tokens.color/font/spacing),"
+        say 'or run `rails g active_mail:styles` to eject and edit the SCSS partials.'
+      end
+
+      private
+
+      def back_up_layout(original)
+        backup = File.join(layouts_base_dir, "old_mailer_#{Time.now.strftime('%Y%m%d%H%M%S%L')}.html.erb")
+        File.rename(File.join(destination_root, original), File.join(destination_root, backup))
+        say "Renamed existing #{original} → #{backup} (it would shadow the new ActiveMail layout).", :yellow
+      end
+
+      def layouts_base_dir
+        File.join('app', 'views', 'layouts')
+      end
+
+      def extension
+        %w[haml slim].find { |ext| options.send(ext) } || 'erb'
+      end
+    end
+  end
+end

data/lib/generators/active_mail/styles_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module ActiveMail
+  module Generators
+    class StylesGenerator < ::Rails::Generators::Base
+      desc 'Copy ActiveMail framework SCSS partials into the host app for customization'
+      source_root File.expand_path('../../../app/assets/stylesheets/active_mail', __dir__)
+
+      TARGET_DIR = File.join('app', 'assets', 'stylesheets', 'active_mail')
+
+      # The .scss.erb token bridge is deliberately not ejected: it needs ERB
+      # preprocessing, and tokens come from Ruby config (rake active_mail:tokens:export).
+      def copy_styles
+        Dir.children(self.class.source_root).each do |name|
+          next if name.end_with?('.erb')
+
+          copy_file name, File.join(TARGET_DIR, name)
+        end
+      end
+
+      def show_readme
+        say "\nEjected the ActiveMail SCSS partials to #{TARGET_DIR}.", :green
+        say 'Token values come from Ruby (config.tokens.color/font/spacing). For a static'
+        say 'SCSS partial of those values, run `rake active_mail:tokens:export`.'
+      end
+    end
+  end
+end

data/lib/generators/active_mail/templates/component.rb.tt

@@ -0,0 +1,13 @@
+# typed: false
+# frozen_string_literal: true
+
+module Components
+  # Register in config/initializers/active_mail.rb:
+  #   config.register_component "<%= tag_name %>", Components::<%= class_name %>
+  class <%= class_name %> < ActiveMail::Components::Base
+    def transform(node, inner)
+      classes = combine_classes(node, "<%= tag_name %>")
+      %(<table class="#{classes}" #{TABLE_RESET}><tbody><tr><td>#{inner}</td></tr></tbody></table>)
+    end
+  end
+end

data/lib/generators/active_mail/templates/initializer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# ActiveMail configuration. Works zero-config; uncomment to customize.
+ActiveMail.configure do |config|
+  # Template engine ActiveMail composes with for `.inky` views (`.inky-erb`,
+  # `.inky-haml`, … are always available regardless of this default).
+  # config.template_engine = :erb
+
+  # Layout geometry.
+  # config.column_count = 12
+  # config.container_width = 600
+
+  # CSS inliner: :premailer (default), :roadie, :null, or a custom
+  # ActiveMail::Inliner::Base subclass/instance.
+  # config.inliner = :premailer
+
+  # Set false if another inliner (e.g. premailer-rails) already runs on mailers.
+  # config.register_inline_interceptor = true
+
+  # How malformed markup is handled: :warn (default), :ignore, or :raise.
+  # config.on_parse_error = :warn
+
+  # Design tokens — the single source of truth, bridged to SCSS via $am-*.
+  # config.tokens.color :primary, "#2a9d8f"
+  # config.tokens.color :secondary, "#264653"
+  # config.tokens.font :heading, "Georgia, serif"
+  # config.tokens.spacing :lg, "32px"
+
+  # Register components (built-ins like ActiveMail::Components::Cta, or your own
+  # Components::* from `rails g active_mail:component`).
+  # config.register_component "cta", ActiveMail::Components::Cta
+end

data/lib/generators/active_mail/templates/mailer_layout.html.inky-erb

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="<%%= I18n.locale %>" xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="x-apple-disable-message-reformatting">
+    <meta name="color-scheme" content="light dark">
+    <meta name="supported-color-schemes" content="light dark">
+    <!--[if mso]>
+    <noscript>
+      <xml>
+        <o:OfficeDocumentSettings>
+          <o:PixelsPerInch>96</o:PixelsPerInch>
+        </o:OfficeDocumentSettings>
+      </xml>
+    </noscript>
+    <![endif]-->
+    <%%= active_mail_inline_styles %>
+    <%%# Fallback for when active_mail_inline_styles cannot read the compiled asset. %>
+    <%%= stylesheet_link_tag "active_mail/active_mail", media: "all" %>
+  </head>
+
+  <body style="margin:0;padding:0;word-spacing:normal;">
+    <div role="article" aria-roledescription="email" lang="<%%= I18n.locale %>" style="width:100%;">
+      <container>
+        <%%= yield %>
+      </container>
+    </div>
+  </body>
+</html>

data/lib/generators/active_mail/templates/mailer_layout.html.inky-haml

@@ -0,0 +1,17 @@
+!!!
+%html{lang: I18n.locale, xmlns: "http://www.w3.org/1999/xhtml", "xmlns:v" => "urn:schemas-microsoft-com:vml", "xmlns:o" => "urn:schemas-microsoft-com:office:office"}
+  %head
+    %meta{charset: "utf-8"}
+    %meta{name: "viewport", content: "width=device-width, initial-scale=1"}
+    %meta{name: "x-apple-disable-message-reformatting"}
+    %meta{name: "color-scheme", content: "light dark"}
+    %meta{name: "supported-color-schemes", content: "light dark"}
+    :plain
+      <!--[if mso]><noscript><xml><o:OfficeDocumentSettings><o:PixelsPerInch>96</o:PixelsPerInch></o:OfficeDocumentSettings></xml></noscript><![endif]-->
+    = active_mail_inline_styles
+    -# Fallback for when active_mail_inline_styles cannot read the compiled asset.
+    = stylesheet_link_tag "active_mail/active_mail", media: "all"
+  %body{style: "margin:0;padding:0;word-spacing:normal;"}
+    %div{role: "article", "aria-roledescription" => "email", lang: I18n.locale, style: "width:100%;"}
+      %container
+        = yield

data/lib/generators/active_mail/templates/mailer_layout.html.inky-slim

@@ -0,0 +1,16 @@
+doctype html
+html lang=I18n.locale xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office"
+  head
+    meta charset="utf-8"
+    meta name="viewport" content="width=device-width, initial-scale=1"
+    meta name="x-apple-disable-message-reformatting"
+    meta name="color-scheme" content="light dark"
+    meta name="supported-color-schemes" content="light dark"
+    | <!--[if mso]><noscript><xml><o:OfficeDocumentSettings><o:PixelsPerInch>96</o:PixelsPerInch></o:OfficeDocumentSettings></xml></noscript><![endif]-->
+    = active_mail_inline_styles
+    / Fallback for when active_mail_inline_styles cannot read the compiled asset.
+    = stylesheet_link_tag "active_mail/active_mail", media: "all"
+  body style="margin:0;padding:0;word-spacing:normal;"
+    div role="article" aria-roledescription="email" lang=I18n.locale style="width:100%;"
+      container
+        = yield

data/lib/generators/active_mail/views_generator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module ActiveMail
+  module Generators
+    class ViewsGenerator < ::Rails::Generators::Base
+      desc 'Copy ActiveMail default layout views into the host app for customization'
+      source_root File.expand_path('../../../app/views/layouts/active_mail', __dir__)
+
+      def copy_views
+        directory '.', File.join('app', 'views', 'layouts', 'active_mail')
+      end
+    end
+  end
+end

data/lib/tasks/active_mail.rake

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'active_mail'
+require 'fileutils'
+
+namespace :active_mail do
+  namespace :tokens do
+    desc 'Export design tokens to a static SCSS partial (for Propshaft apps that cannot preprocess .scss.erb)'
+    # :environment so the host initializer's config.tokens overrides are loaded.
+    task :export, [:path] => :environment do |_task, args|
+      path = args[:path] || 'app/assets/stylesheets/active_mail/_active_mail_tokens.scss'
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, ActiveMail.scss_variables)
+      puts "Wrote #{ActiveMail.tokens.colors.size + ActiveMail.tokens.fonts.size + ActiveMail.tokens.spacings.size} tokens to #{path}"
+    end
+  end
+
+  namespace :emails do
+    desc 'Render every host mailer preview to disk and run the quality guard on each'
+    task render_all: :environment do
+      require 'active_mail/quality/render_all'
+
+      config = ActiveMail::Quality.config
+      output_root = defined?(Rails) && Rails.respond_to?(:root) ? Rails.root.join(config.output_dir) : Pathname(config.output_dir)
+      result = ActiveMail::Quality::RenderAll.new(output_root: output_root, config: config).call
+      puts "Rendered #{result.rendered} email(s) into #{output_root}"
+      # A green run on zero previews would silently verify nothing — make it visible.
+      warn '[activemail] WARNING: no mailer previews were discovered — nothing was checked.' if result.discovered.zero?
+      result.render_failures.each { |key, error| puts "  render failed: #{key}: #{error}" }
+      result.guard_failures.each do |key, violations|
+        puts "  guard failed: #{key}", violations.map { |v| "    - [#{v.rule}] #{v.message}" }.join("\n")
+      end
+      abort "\n#{result.broken_required.size} required preview(s) failed: #{result.broken_required.join(', ')}" if result.broken_required.any?
+    end
+  end
+end