activemail 1.2.3 → 2.1.0

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 = {}
+        @config.check_exemptions!(@config.guard)
+        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)
+      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
-      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 { 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?
 
-      sig do
-        params(preview: T.untyped, email: String, failures: T::Hash[String, String], key: String).returns(T.nilable(Pathname))
+        @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|
+          write(preview, email, locale, mail) unless PreviewRenderer.declined?(mail)
+          key = PreviewRenderer.key(preview, email)
+          @config.guard.violations(mail, allow_declined: @config.allow_declined?(key), skip: @config.exempt_rules_for(key))
+        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,20 +6,20 @@ 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)
+        sig { params(guard: Guard, allow_declined: T::Boolean, skip: T::Array[Symbol]).void }
+        def initialize(guard: ActiveMail::Quality.guard, allow_declined: false, skip: Guard::NO_SKIP)
           @guard = T.let(guard, Guard)
+          @allow_declined = T.let(allow_declined, T::Boolean)
+          @skip = T.let(skip, T::Array[Symbol])
           @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, allow_declined: @allow_declined, skip: @skip)
           @violations.empty?
         end
 
@@ -42,7 +42,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,15 +50,16 @@ 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
 
-      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)
+      sig do
+        params(guard: ActiveMail::Quality::Guard, allow_declined: T::Boolean, skip: T::Array[Symbol])
+          .returns(ActiveMail::Quality::Rspec::ValidEmailMatcher)
+      end
+      def be_a_valid_email(guard: ActiveMail::Quality.guard, allow_declined: false, skip: ActiveMail::Quality::Guard::NO_SKIP)
+        ActiveMail::Quality::Rspec::ValidEmailMatcher.new(guard: guard, allow_declined: allow_declined, skip: skip)
       end
     end
   end

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/quality/rule_exemptions.rb

@@ -0,0 +1,49 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+require_relative 'guard'
+
+module ActiveMail
+  module Quality
+    # Rules a preview is exempt from, keyed by preview name (every email of it) or by
+    # preview key ("preview_name#email"); values are rule names, built-in or custom.
+    module RuleExemptions
+      extend T::Sig
+
+      sig { returns(T::Hash[String, T::Array[Symbol]]) }
+      def rule_exemptions
+        exemptions.dup.freeze
+      end
+
+      sig { params(value: T.untyped).void }
+      def rule_exemptions=(value)
+        Kernel.raise TypeError, "rule_exemptions must be a Hash, got #{value.class}" unless value.is_a?(Hash)
+
+        exemptions = value.to_h { |key, rules| [key.to_s.freeze, Kernel.Array(rules).map(&:to_sym).freeze] }
+        @exemptions = T.let(exemptions, T.nilable(T::Hash[String, T::Array[Symbol]]))
+      end
+
+      sig { params(key: String).returns(T::Array[Symbol]) }
+      def exempt_rules_for(key)
+        by_key = exemptions.fetch(key, Guard::NO_SKIP)
+        by_name = exemptions.fetch(key.split('#', 2).first.to_s, Guard::NO_SKIP)
+        by_key.empty? ? by_name : by_key | by_name
+      end
+
+      # Called before any preview renders: a bad name would otherwise surface as a render failure, or a skip.
+      sig { params(guard: Guard).void }
+      def check_exemptions!(guard)
+        exemptions.each_value { |rules| guard.check_skippable!(rules) }
+      end
+
+      private
+
+      sig { returns(T::Hash[String, T::Array[Symbol]]) }
+      def exemptions
+        @exemptions ||= T.let({}, T.nilable(T::Hash[String, T::Array[Symbol]]))
+      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,78 @@
+# 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',
+        container_gutter: '16px'
+      }.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