activemail 1.2.3 → 2.0.0

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

data/lib/activemail/quality/rule.rb

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module ActiveMail
+  module Quality
+    # :html rules receive (Nokogiri document, html), :message rules the mail; a check
+    # returns nil/false to pass, else one message or an Array of them.
+    class Rule
+      extend T::Sig
+
+      LEVELS = T.let(%i[html message].freeze, T::Array[Symbol])
+
+      sig { returns(Symbol) }
+      attr_reader :name
+
+      sig { returns(Symbol) }
+      attr_reader :level
+
+      sig { params(name: Symbol, level: Symbol, check: Proc).void }
+      def initialize(name, level, check)
+        raise ArgumentError, "rule level must be one of #{LEVELS.inspect}, got #{level.inspect}" unless LEVELS.include?(level)
+
+        @name = name
+        @level = level
+        @check = check
+      end
+
+      sig { params(name: Symbol, check: Proc).returns(Rule) }
+      def self.html(name, &check)
+        new(name, :html, check)
+      end
+
+      sig { params(name: Symbol, check: Proc).returns(Rule) }
+      def self.message(name, &check)
+        new(name, :message, check)
+      end
+
+      sig { params(args: T::Array[T.untyped]).returns(T::Array[String]) }
+      def messages(args)
+        result = T.unsafe(@check).call(*args)
+        result ? Array(result).map(&:to_s) : []
+      end
+    end
+  end
+end

data/lib/activemail/rails/engine.rb

@@ -2,28 +2,28 @@
 # frozen_string_literal: true
 
 require 'rails/engine'
-require 'activemail/rails/compiled_stylesheet'
+require 'activemail/asset_pipeline'
+require 'activemail/rails/rendering'
 
 module ActiveMail
   module Rails
     class Engine < ::Rails::Engine
-      config.annotations.register_extensions('activemail') { |annotation| /<!--\s*(#{annotation}):?\s*(.*) -->/ } if config.respond_to?(:annotations)
-
-      # Sprockets only compiles whitelisted assets; the framework entry must be
-      # reachable as `stylesheet_link_tag "activemail/activemail"` from a host.
+      # Sprockets only compiles whitelisted assets (a no-op under Propshaft).
       initializer 'activemail.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[activemail/activemail.css] if assets.respond_to?(:precompile)
+        ActiveMail::AssetPipeline.for(app).register_precompile(%w[activemail/activemail.css])
+      end
+
+      initializer 'activemail.annotations' do |app|
+        ActiveSupport.on_load(:action_view) do
+          extensions = ActionView::Template.template_handler_extensions.grep(/\Ainky-/)
+          app.config.annotations.register_extensions(*extensions) { |annotation| /<!--\s*(#{annotation}):?\s*(.*) -->/ }
+        end
       end
 
       initializer 'activemail.action_mailer' do
         ActiveSupport.on_load(:action_mailer) do
-          require 'activemail/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
-          # activemail_inline_styles must be available to mailer layouts/views.
+          prepend ActiveMail::Rails::Rendering::MailerExtension
+
           helper ActiveMail::StylesHelper
         end
       end

data/lib/activemail/rails/rendering.rb

@@ -0,0 +1,51 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'active_support/isolated_execution_state'
+
+module ActiveMail
+  module Rails
+    # Handlers only mark the scope; the pipeline runs once at its exit, so a
+    # layout wrapping a view never re-transpiles it.
+    module Rendering
+      STATE_KEY = :activemail_render_scope
+
+      class Scope
+        attr_accessor :inky_html
+      end
+
+      class << self
+        def scoped
+          return yield if current
+
+          scope = Scope.new
+          ActiveSupport::IsolatedExecutionState[STATE_KEY] = scope
+          body = yield
+          scope.inky_html ? ActiveMail::Pipeline.call(body.to_s).html_safe : body
+        ensure
+          ActiveSupport::IsolatedExecutionState[STATE_KEY] = nil if scope
+        end
+
+        def process(output, format)
+          scope = current
+          return ActiveMail.configuration.core.transpile(output) unless scope
+
+          scope.inky_html = true if format.nil? || format == :html
+          output
+        end
+
+        private
+
+        def current
+          ActiveSupport::IsolatedExecutionState[STATE_KEY]
+        end
+      end
+
+      module MailerExtension
+        def render_to_body(options = {})
+          ActiveMail::Rails::Rendering.scoped { super }
+        end
+      end
+    end
+  end
+end

data/lib/activemail/rails/template_handler.rb

@@ -3,6 +3,8 @@
 
 require 'sorbet-runtime'
 
+require_relative 'rendering'
+
 module ActiveMail
   module Rails
     class TemplateHandler
@@ -37,7 +39,7 @@ module ActiveMail
           else
             engine_handler.call(template)
           end
-        "ActiveMail::Core.new.transpile(begin; #{compiled_source};end)"
+        "ActiveMail::Rails::Rendering.process(begin; #{compiled_source};end, #{template.format.inspect})"
       end
 
       module Composer

data/lib/activemail/tokens/button_style.rb

@@ -14,12 +14,11 @@ module ActiveMail
       const :radius, String
       const :border, T.nilable(String)
 
-      # color falls back to :button_text; border is opt-in (a "<variant>_border" token).
       sig { params(tokens: ActiveMail::Tokens, variant: T.any(String, Symbol)).returns(ButtonStyle) }
       def self.from(tokens, variant)
         new(
           background: tokens.color!(variant),
-          color: tokens.color("#{variant}_text") || tokens.color!(:button_text),
+          color: tokens.color!("#{variant}_text"),
           radius: tokens.radius!(:button),
           border: tokens.color("#{variant}_border")
         )

data/lib/activemail/tokens/defaults.rb

@@ -0,0 +1,77 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module ActiveMail
+  class Tokens
+    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
+    )
+
+    DEFAULT_RADII = T.let(
+      {
+        button: '4px',
+        box: '4px'
+      }.freeze,
+      TokenMap
+    )
+
+    # Optional colors resolve to another token (nil: unset) so components and the
+    # SCSS bridge read the same value whether or not the host configured them.
+    DERIVED_COLORS = T.let(
+      {
+        primary_text: :button_text,
+        primary_border: nil,
+        secondary_text: :button_text,
+        secondary_border: nil,
+        info_box_background: :background,
+        info_box_border: :border,
+        info_box_text: :text
+      }.freeze,
+      T::Hash[Symbol, T.nilable(Symbol)]
+    )
+
+    GROUPS = T.let(
+      {
+        color: DEFAULT_COLORS,
+        font: DEFAULT_FONTS,
+        spacing: DEFAULT_SPACINGS,
+        radius: DEFAULT_RADII
+      }.freeze,
+      T::Hash[Symbol, TokenMap]
+    )
+  end
+end

data/lib/activemail/tokens/scss_serializer.rb

@@ -5,15 +5,15 @@ require 'sorbet-runtime'
 
 module ActiveMail
   class Tokens
-    # !default lets a host pre-declare overrides upstream. Values are emitted
-    # verbatim (trusted, app-controlled input) — not escaped.
+    # !default lets a host configure overrides upstream. Values are emitted
+    # verbatim (trusted, app-controlled input) — not escaped; nil becomes Sass null.
     module ScssSerializer
       extend T::Sig
 
-      sig { params(stores: T::Hash[Symbol, TokenMap]).returns(String) }
+      sig { params(stores: T::Hash[Symbol, T::Hash[Symbol, T.nilable(String)]]).returns(String) }
       def self.call(stores)
         lines = stores.flat_map do |group, store|
-          store.map { |name, value| "$am-#{group}-#{name.to_s.tr('_', '-')}: #{value} !default;" }
+          store.map { |name, value| "$am-#{group}-#{name.to_s.tr('_', '-')}: #{value || 'null'} !default;" }
         end
         "#{lines.join("\n")}\n"
       end