activemail 1.0.0

data/lib/active_mail/quality/guard.rb

@@ -0,0 +1,131 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'sorbet-runtime'
+
+require_relative '../libxml'
+
+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
+        const :rule, Symbol
+        const :message, String
+      end
+
+      DISABLEABLE = T.let(%i[max_bytes parse_error table_role img_alt lang min_full_doc_bytes].freeze, T::Array[Symbol])
+      # 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])
+      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
+
+      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
+      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)")
+      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?
+
+        violations << Violation.new(rule: :parse_error, message: "malformed HTML: #{errors.first(3).map { |e| e.message.to_s.strip }.join('; ')}")
+      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?
+
+        violations << Violation.new(rule: :table_role, message: %(#{offenders} <table> missing role="presentation"))
+      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")
+      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)
+      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
+end

data/lib/active_mail/quality/minitest.rb

@@ -0,0 +1,64 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../quality'
+
+module ActiveMail
+  module Quality
+    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")}"
+      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)
+      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
+          # 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
+          end
+        end
+      end
+
+      sig { params(base: T.untyped).void }
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      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)
+      rescue StandardError => e
+        msg = "#{key} did not render (#{e.class}: #{e.message})"
+        required.include?(key) ? T.unsafe(self).flunk("required preview #{msg}") : T.unsafe(self).skip(msg)
+      end
+    end
+  end
+end

data/lib/active_mail/quality/preview_renderer.rb

@@ -0,0 +1,70 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+require 'sorbet-runtime'
+
+module ActiveMail
+  module Quality
+    module PreviewRenderer
+      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
+        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)
+
+          ActionMailer::Preview.all.flat_map do |preview|
+            preview.emails.map { |email| [preview, email] }
+          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
+
+          body.respond_to?(:decoded) ? body.decoded : body.to_s
+        end
+
+        private
+
+        # 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?
+
+          mail.body if mail.mime_type.nil? || mail.mime_type == 'text/html'
+        end
+      end
+    end
+  end
+end

data/lib/active_mail/quality/render_all.rb

@@ -0,0 +1,90 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'fileutils'
+
+require_relative '../quality'
+
+module ActiveMail
+  module Quality
+    # Render + guard every host preview; lives here (not the Rakefile) to stay unit-testable.
+    class RenderAll
+      extend T::Sig
+
+      class Result < T::Struct
+        const :discovered, Integer
+        const :rendered, Integer
+        const :render_failures, T::Hash[String, String]
+        const :guard_failures, T::Hash[String, T::Array[Guard::Violation]]
+        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)
+        @config = T.let(config, Configuration)
+      end
+
+      sig { returns(Result) }
+      def call
+        FileUtils.rm_rf(@output_root)
+        FileUtils.mkdir_p(@output_root)
+
+        render_failures = {}
+        guard_failures = {}
+        previews = PreviewRenderer.all
+        rendered = render_all(previews, render_failures, guard_failures)
+
+        Result.new(
+          discovered: previews.size, rendered: rendered, render_failures: render_failures,
+          guard_failures: guard_failures, broken_required: broken_required(previews, render_failures, guard_failures)
+        )
+      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])
+      end
+      def broken_required(previews, render_failures, guard_failures)
+        required = @config.required_previews
+        discovered = previews.map { |preview, email| PreviewRenderer.key(preview, email) }
+        ((render_failures.keys | guard_failures.keys) & 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
+      end
+
+      sig do
+        params(preview: T.untyped, email: String, failures: T::Hash[String, String], key: String).returns(T.nilable(Pathname))
+      end
+      def render_one(preview, email, failures, key)
+        PreviewRenderer.render_to_disk(preview, email, @output_root)
+      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}"
+        nil
+      end
+    end
+  end
+end

data/lib/active_mail/quality/rspec.rb

@@ -0,0 +1,65 @@
+# typed: strict
+# frozen_string_literal: true
+
+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
+
+        sig { params(guard: Guard).void }
+        def initialize(guard: ActiveMail::Quality.guard)
+          @guard = T.let(guard, Guard)
+          @violations = T.let([], T::Array[Guard::Violation])
+        end
+
+        sig { params(html: String).returns(T::Boolean) }
+        def matches?(html)
+          @violations = @guard.violations(html)
+          @violations.empty?
+        end
+
+        sig { returns(String) }
+        def failure_message
+          "expected email HTML to be valid, but found violations:\n#{formatted_violations}"
+        end
+
+        sig { returns(String) }
+        def failure_message_when_negated
+          'expected email HTML to have quality violations, but it was valid'
+        end
+
+        sig { returns(String) }
+        def description
+          'be a valid email'
+        end
+
+        private
+
+        sig { returns(String) }
+        def formatted_violations
+          @violations.map { |v| "  - [#{v.rule}] #{v.message}" }.join("\n")
+        end
+      end
+    end
+  end
+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
+
+      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)
+      end
+    end
+  end
+end

data/lib/active_mail/quality.rb

@@ -0,0 +1,38 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+require_relative 'quality/guard'
+require_relative 'quality/configuration'
+require_relative 'quality/preview_renderer'
+
+module ActiveMail
+  # Opt-in email-quality layer. Host apps require this explicitly from their test
+  # suite; `require 'active_mail'` must NOT pull it in.
+  module Quality
+    extend T::Sig
+
+    sig { returns(Configuration) }
+    def self.config
+      @config ||= T.let(Configuration.new, T.nilable(Configuration))
+    end
+
+    sig { params(config: T.untyped).returns(Configuration) }
+    def self.config=(config)
+      raise TypeError, 'Not an ActiveMail::Quality::Configuration' unless config.is_a?(Configuration)
+
+      @config = config
+    end
+
+    sig { params(block: T.proc.params(config: Configuration).void).void }
+    def self.configure(&block)
+      block.call(config)
+    end
+
+    sig { returns(Guard) }
+    def self.guard
+      config.guard
+    end
+  end
+end

data/lib/active_mail/rails/compiled_stylesheet.rb

@@ -0,0 +1,62 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module ActiveMail
+  # Reads a compiled CSS asset's bytes (Sprockets or Propshaft, by duck-type) — the
+  # bytes, not a digest URL, are what the Premailer adapter needs to inline.
+  module CompiledStylesheet
+    class << self
+      extend T::Sig
+
+      # '' (not nil) on a miss: callers embed the result verbatim, and a missing
+      # asset must degrade to an empty <style>, never interpolate "nil" into HTML.
+      sig { params(logical_path: String).returns(String) }
+      def read(logical_path)
+        sprockets_source(logical_path) || propshaft_source(logical_path) || ''
+      end
+
+      private
+
+      # Sprockets: config.assets.compile (dev) resolves logical paths in-memory;
+      # precompiled (prod) resolves through the manifest. #find_asset covers both.
+      sig { params(logical_path: String).returns(T.nilable(String)) }
+      def sprockets_source(logical_path)
+        assets = rails_assets_environment
+        return unless assets.respond_to?(:find_asset)
+
+        asset = assets.find_asset(logical_path)
+        asset&.source&.to_s
+      end
+
+      # Propshaft: the load_path resolves a logical path to a compiled file on disk.
+      sig { params(logical_path: String).returns(T.nilable(String)) }
+      def propshaft_source(logical_path)
+        assets = rails_assets
+        load_path = assets.respond_to?(:load_path) ? assets.load_path : nil
+        return unless load_path.respond_to?(:find)
+
+        asset = load_path.find(logical_path)
+        asset&.path && File.exist?(asset.path) ? File.read(asset.path) : nil
+      end
+
+      # config.assets.environment is the Sprockets::Environment; absent under Propshaft.
+      sig { returns(T.untyped) }
+      def rails_assets_environment
+        assets = rails_assets
+        assets.respond_to?(:environment) ? assets.environment : nil
+      end
+
+      sig { returns(T.untyped) }
+      def rails_assets
+        return unless Object.const_defined?(:Rails)
+
+        rails = Object.const_get(:Rails)
+        app = rails.respond_to?(:application) ? rails.application : nil
+        config = app&.config
+        config.respond_to?(:assets) ? config.assets : nil
+      end
+    end
+  end
+end

data/lib/active_mail/rails/engine.rb

@@ -0,0 +1,36 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'rails/engine'
+require 'active_mail/rails/compiled_stylesheet'
+
+module ActiveMail
+  module Rails
+    class Engine < ::Rails::Engine
+      config.annotations.register_extensions('active_mail') { |annotation| /<!--\s*(#{annotation}):?\s*(.*) -->/ } if config.respond_to?(:annotations)
+
+      # Sprockets only compiles whitelisted assets; the framework entry must be
+      # reachable as `stylesheet_link_tag "active_mail/active_mail"` from a host.
+      initializer 'active_mail.assets' do |app|
+        # Propshaft exposes config.assets but no #precompile (Sprockets-only).
+        assets = app.config.respond_to?(:assets) ? app.config.assets : nil
+        assets.precompile += %w[active_mail/active_mail.css] if assets.respond_to?(:precompile)
+      end
+
+      initializer 'active_mail.action_mailer' do
+        ActiveSupport.on_load(:action_mailer) do
+          require 'active_mail/inliner/interceptor'
+          # The interceptor honors config.register_inline_interceptor (and inliner =
+          # :null) at delivery time — a boot-time check would precede host config.
+          register_interceptor ActiveMail::Inliner::Interceptor
+          # active_mail_inline_styles must be available to mailer layouts/views.
+          helper ActiveMail::StylesHelper
+        end
+      end
+
+      rake_tasks do
+        load File.expand_path('../../tasks/active_mail.rake', __dir__)
+      end
+    end
+  end
+end

data/lib/active_mail/rails/template_handler.rb

@@ -0,0 +1,62 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module ActiveMail
+  module Rails
+    class TemplateHandler
+      extend T::Sig
+
+      sig { params(compose_with: T.nilable(T.any(String, Symbol))).void }
+      def initialize(compose_with = nil)
+        # ActionView handlers share no interface (Procs, objects, classes).
+        @engine_handler = T.let(nil, T.untyped)
+        return unless compose_with
+
+        # Without this guard a typo would silently fall back to the configured
+        # template_engine in #engine_handler.
+        @engine_handler = ActionView::Template.registered_template_handler(compose_with) ||
+                          raise(ArgumentError, "No template handler found for #{compose_with}")
+      end
+
+      sig { returns(T.untyped) }
+      def engine_handler
+        return @engine_handler if @engine_handler
+
+        type = ::ActiveMail.configuration.template_engine
+        ActionView::Template.registered_template_handler(type) ||
+          raise("No template handler found for #{type}")
+      end
+
+      sig { params(template: T.untyped, source: T.nilable(String)).returns(String) }
+      def call(template, source = nil)
+        compiled_source =
+          if source
+            engine_handler.call(template, source)
+          else
+            engine_handler.call(template)
+          end
+        "ActiveMail::Core.new.release_the_kraken(begin; #{compiled_source};end)"
+      end
+
+      module Composer
+        extend T::Sig
+
+        sig { params(ext: T.untyped, args: T.untyped).returns(T.untyped) }
+        def register_template_handler(ext, *args)
+          super
+          super(:"inky-#{ext}", ActiveMail::Rails::TemplateHandler.new(ext))
+        end
+      end
+    end
+  end
+end
+
+ActiveSupport.on_load(:action_view) do
+  ActionView::Template.template_handler_extensions.each do |ext|
+    ActionView::Template.register_template_handler :"inky-#{ext}", ActiveMail::Rails::TemplateHandler.new(ext)
+  end
+  ActionView::Template.register_template_handler :inky, ActiveMail::Rails::TemplateHandler.new
+  ActionView::Template.singleton_class.send :prepend, ActiveMail::Rails::TemplateHandler::Composer
+end