activeadmin_batched_export 0.1.0

data/app/views/active_admin/batched_export/_filters.html.erb

@@ -0,0 +1,11 @@
+<div class="<%= styles[:card] %>">
+  <%= render partial: "active_admin/resource/active_filters", locals: {active_filters: @batched_export_active_filters} %>
+</div>
+
+<div class="space-y-2">
+  <h2 class="<%= styles[:heading] %>"><%= t("active_admin.batched_export") %></h2>
+  <p class="<%= styles[:hint] %>"><%= t("active_admin.batched_export_page.blurb") %></p>
+  <% if @batched_export_large_export %>
+    <p class="<%= styles[:warning] %>"><%= t("active_admin.batched_export_page.large_export_warning") %></p>
+  <% end %>
+</div>

data/app/views/active_admin/batched_export/_progress.html.erb

@@ -0,0 +1,14 @@
+<div class="<%= styles[:progress_wrap] %>" data-<%= stimulus_controller %>-target="progressWrap">
+  <div class="<%= styles[:progress_status_row] %>">
+    <span data-<%= stimulus_controller %>-target="status"><%= t("active_admin.batched_export_page.preparing") %></span>
+    <span data-<%= stimulus_controller %>-target="fraction"></span>
+  </div>
+  <progress
+    value="0"
+    max="100"
+    class="<%= styles[:progress_bar] %>"
+    data-<%= stimulus_controller %>-target="bar"
+  ></progress>
+</div>
+
+<p class="<%= styles[:error] %>" data-<%= stimulus_controller %>-target="error"></p>

data/app/views/active_admin/batched_export/_summary.html.erb

@@ -0,0 +1,40 @@
+<% preview = @batched_export_preview %>
+<div class="<%= styles[:card] %>">
+  <h3 class="<%= styles[:card_title] %>"><%= t("active_admin.batched_export_page.summary_title") %></h3>
+  <table class="<%= styles[:table] %>">
+    <tbody class="<%= styles[:table_body] %>">
+      <tr class="<%= styles[:table_row] %>">
+        <th scope="row" class="<%= styles[:table_header] %>"><%= t("active_admin.batched_export_page.resource_label") %></th>
+        <td class="<%= styles[:table_cell] %>"><%= active_admin_config.plural_resource_label %></td>
+      </tr>
+      <tr class="<%= styles[:table_row] %>">
+        <th scope="row" class="<%= styles[:table_header] %>"><%= t("active_admin.batched_export_page.scope_label") %></th>
+        <td class="<%= styles[:table_cell] %>"><%= current_scope ? scope_name(current_scope) : "—" %></td>
+      </tr>
+      <tr class="<%= styles[:table_row] %>">
+        <th scope="row" class="<%= styles[:table_header] %>"><%= t("active_admin.batched_export_page.sort_label") %></th>
+        <td class="<%= styles[:table_cell] %>"><%= @batched_export_sort_description %></td>
+      </tr>
+      <tr class="<%= styles[:table_row] %>">
+        <th scope="row" class="<%= styles[:table_header] %>"><%= t("active_admin.batched_export_page.format_label") %></th>
+        <td class="<%= styles[:table_cell] %>"><%= preview[:export_format].to_s.upcase %></td>
+      </tr>
+      <tr class="<%= styles[:table_row] %>">
+        <th scope="row" class="<%= styles[:table_header] %>"><%= t("active_admin.batched_export_page.total_rows_label") %></th>
+        <td class="<%= styles[:table_cell] %>"><%= number_with_delimiter(preview[:total_count]) %></td>
+      </tr>
+      <tr class="<%= styles[:table_row] %>">
+        <th scope="row" class="<%= styles[:table_header] %>"><%= t("active_admin.batched_export_page.batches_label") %></th>
+        <td class="<%= styles[:table_cell] %>"><%= number_with_delimiter(preview[:total_batches]) %></td>
+      </tr>
+      <tr class="<%= styles[:table_row] %>">
+        <th scope="row" class="<%= styles[:table_header] %>"><%= t("active_admin.batched_export_page.batch_size_label") %></th>
+        <td class="<%= styles[:table_cell] %>"><%= number_with_delimiter(preview[:batch_size]) %></td>
+      </tr>
+      <tr>
+        <th scope="row" class="<%= styles[:table_header] %>"><%= t("active_admin.batched_export_page.filename_label") %></th>
+        <td class="<%= styles[:table_cell_mono] %>"><%= preview[:filename] %></td>
+      </tr>
+    </tbody>
+  </table>
+</div>

data/app/views/active_admin/batched_export/workspace.html.erb

@@ -0,0 +1,22 @@
+<% styles = @batched_export_styles %>
+<% stimulus_controller = @batched_export_stimulus_controller %>
+<div
+  class="<%= styles[:workspace] %>"
+  data-controller="<%= stimulus_controller %>"
+  data-<%= stimulus_controller %>-meta-url-value="<%= @batched_export_meta_url %>"
+  data-<%= stimulus_controller %>-meta-value="<%= @batched_export_preview.to_json %>"
+  data-<%= stimulus_controller %>-batch-base-url-value="<%= @batched_export_batch_base_url %>"
+  data-<%= stimulus_controller %>-format-value="<%= @batched_export_format %>"
+  data-<%= stimulus_controller %>-preparing-message-value="<%= t("active_admin.batched_export_page.preparing") %>"
+  data-<%= stimulus_controller %>-loading-batch-template-value="<%= t("active_admin.batched_export_page.loading_batch") %>"
+  data-<%= stimulus_controller %>-empty-message-value="<%= t("active_admin.batched_export_page.empty") %>"
+  data-<%= stimulus_controller %>-failed-batch-template-value="<%= t("active_admin.batched_export_page.failed_batch") %>"
+  data-<%= stimulus_controller %>-ready-message-value="<%= t("active_admin.batched_export_page.ready") %>"
+  data-<%= stimulus_controller %>-needs-column-message-value="<%= t("active_admin.batched_export_page.select_at_least_one_column") %>"
+>
+  <%= render "active_admin/batched_export/summary", styles: styles %>
+  <%= render "active_admin/batched_export/columns", styles: styles, stimulus_controller: stimulus_controller %>
+  <%= render "active_admin/batched_export/filters", styles: styles %>
+  <%= render "active_admin/batched_export/progress", styles: styles, stimulus_controller: stimulus_controller %>
+  <%= render "active_admin/batched_export/actions", styles: styles, stimulus_controller: stimulus_controller %>
+</div>

data/app/views/active_admin/shared/_download_format_links.html.erb

@@ -0,0 +1,7 @@
+<% export_base_params = request.query_parameters.except(:format, :commit, :page, :batch_page, :export_meta) %>
+<div>
+  <span><%= I18n.t("active_admin.download") %></span>
+  <% formats.each do |format| %>
+    <%= link_to format.upcase, url_for(action: :batched_export, params: export_base_params.merge(export_format: format)) %>
+  <% end %>
+</div>

data/config/locales/activeadmin_batched_export.en.yml

@@ -0,0 +1,29 @@
+en:
+  active_admin:
+    batched_export: Export download
+    batched_export_page:
+      back_to_list: Back to list
+      batch_size_label: Rows per batch
+      batches_label: Download batches
+      blurb: The export loads in separate batches (one HTTP request per batch). Rows are not shown on this page. When loading finishes, use Save file to store the export on your computer.
+      columns_hint: All columns are included by default. Uncheck any you do not need.
+      columns_title: Columns to include
+      empty: There is nothing to export for this filter.
+      failed_batch: "Could not load batch %{page}: %{message}"
+      filename_label: File name
+      format_label: File format
+      large_export_warning: This export is large. The browser keeps the full file in memory before you save it. Narrow filters or export fewer columns if the tab becomes slow.
+      loading_batch: Loading batch %{current} of %{total}
+      preparing: Preparing…
+      ready: Ready. You can save the file now.
+      resource_label: Resource
+      save_file: Save file
+      scope_label: Scope
+      select_at_least_one_column: Select at least one column to export.
+      sort_ascending: ascending
+      sort_descending: descending
+      sort_label: Sort order
+      start: Load export
+      summary_title: What you are exporting
+      total_rows_label: Rows to export
+      unknown_macro: Unknown export macro

data/config/polyrun_coverage.yml

@@ -0,0 +1,7 @@
+track_under:
+  - lib
+minimum_line_percent: 50
+report_formats:
+  - html
+  - cobertura
+  - console

data/lib/activeadmin/batched_export/configuration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "activeadmin/batched_export/styles"
+require "activeadmin/batched_export/export_macro_catalog"
+
+module ActiveAdmin
+  module BatchedExport
+    class Configuration
+      attr_accessor :styles, :batch_size, :max_batch_size, :large_export_row_threshold, :stimulus_controller,
+        :default_enabled, :default_column_selection
+
+      def initialize
+        @styles = Styles.new
+        @batch_size = 1000
+        @max_batch_size = 10_000
+        @large_export_row_threshold = 25_000
+        @stimulus_controller = "activeadmin-batched-export--batched-export"
+        @default_enabled = true
+        @default_column_selection = true
+        @filename_proc = nil
+        @registered_macros = {}
+      end
+
+      attr_reader :filename_proc, :registered_macros
+
+      def filename_proc=(callable)
+        raise ArgumentError, "filename_proc must respond to :call" unless callable.respond_to?(:call)
+
+        @filename_proc = callable
+      end
+
+      def register_macro(name, callable)
+        ExportMacroCatalog.register(name, callable, registry: @registered_macros)
+      end
+    end
+  end
+end

data/lib/activeadmin/batched_export/controller_methods.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require "builder"
+require "csv"
+
+module ActiveAdmin
+  module BatchedExport
+    module ControllerMethods
+      extend ActiveSupport::Concern
+
+      def batched_export
+        authorize! ActiveAdmin::Authorization::READ, active_admin_config.resource_class
+        export_format = normalized_export_format
+        return if export_format.nil?
+
+        if request.format.json? && params[:export_meta].present?
+          ensure_batch_download_format_allowed!(export_format)
+          return render(json: batched_export_meta(export_format))
+        end
+
+        batch_page = params[:batch_page].to_i
+        if batch_page.positive?
+          if request.format.symbol != export_format
+            head :not_acceptable
+            return
+          end
+          ensure_batch_download_format_allowed!(export_format)
+          page = page_relation(batch_page)
+          if page.out_of_range?
+            head :not_found
+            return
+          end
+          begin
+            body = batched_export_batch_body(export_format, batch_page, page: page)
+          rescue ExportMacroCatalog::UnknownMacroError
+            return render(
+              plain: I18n.t("active_admin.batched_export_page.unknown_macro"),
+              status: :unprocessable_content
+            )
+          end
+          return render(plain: body, content_type: batch_content_type(export_format))
+        end
+
+        ensure_batch_download_format_allowed!(export_format)
+        @batched_export_format = export_format
+        @batched_export_meta_url = batched_export_url_for(
+          request_format: :json,
+          extra_params: {"export_meta" => "1", "export_format" => export_format.to_s}
+        )
+        @batched_export_batch_base_url = batched_export_url_for(
+          request_format: export_format,
+          extra_params: {"export_format" => export_format.to_s}
+        )
+        @batched_export_styles = BatchedExport.styles
+        @batched_export_stimulus_controller = BatchedExport.config.stimulus_controller
+        assign_batched_export_workspace_extras!(export_format)
+        render "active_admin/batched_export/workspace", layout: "active_admin"
+      end
+
+      private
+
+      def normalized_export_format
+        format_name = params[:export_format].to_s.downcase
+        format_name = "csv" if format_name.blank?
+        unless %w[csv xml json].include?(format_name)
+          render(plain: "Invalid export format", status: :bad_request)
+          return nil
+        end
+        format_name.to_sym
+      end
+
+      def batched_export_url_for(request_format:, extra_params: {})
+        query = request.query_parameters.except(:format, :commit, :page, :batch_page, :export_meta)
+        hash = query.respond_to?(:to_unsafe_h) ? query.to_unsafe_h : query.to_h
+        hash = hash.merge(extra_params.stringify_keys)
+        url_for(action: :batched_export, format: request_format, params: hash, only_path: true)
+      end
+
+      def ensure_batch_download_format_allowed!(format_symbol)
+        return if format_symbol == :html
+
+        presenter = active_admin_config.get_page_presenter(:index)
+        download_links = (presenter || {}).fetch(:download_links, active_admin_config.namespace.download_links)
+        allowed = build_download_formats(download_links)
+        unless allowed.include?(format_symbol)
+          raise ActiveAdmin::AccessDenied.new(current_active_admin_user, :index)
+        end
+      end
+
+      def batched_export_meta(export_format)
+        base = find_collection(except: [:pagination])
+        first_page = paginate(base, 1, effective_batch_size)
+        total_count = first_page.total_count
+        total_batches = total_count.zero? ? 0 : first_page.total_pages
+        {
+          export_format: export_format,
+          total_count: total_count,
+          total_batches: total_batches,
+          batch_size: effective_batch_size,
+          filename: export_filename(export_format),
+          large_export: total_count >= BatchedExport.config.large_export_row_threshold
+        }
+      end
+
+      def export_filename(format_symbol)
+        filename_proc = active_admin_config.batched_export_filename_proc
+        if filename_proc
+          return filename_proc.call(active_admin_config, format_symbol, self)
+        end
+
+        base = resource_collection_name.to_s.tr("_", "-")
+        "#{base}-#{Time.zone.now.to_date}.#{format_symbol}"
+      end
+
+      def batched_export_batch_body(export_format, batch_page, page: nil)
+        case export_format
+        when :csv then batched_csv_chunk(batch_page, page: page)
+        when :json then batched_json_chunk(batch_page, page: page)
+        when :xml then batched_xml_chunk(batch_page, page: page)
+        else ""
+        end
+      end
+
+      def batch_content_type(export_format)
+        case export_format
+        when :csv then "text/csv; charset=utf-8"
+        when :json then "application/json; charset=utf-8"
+        when :xml then "application/xml; charset=utf-8"
+        else "text/plain; charset=utf-8"
+        end
+      end
+
+      def batched_csv_chunk(batch_page, page: nil)
+        builder = active_admin_config.csv_builder
+        options = builder.options.dup
+        csv_options = options.except(:encoding_options, :humanize_name, :byte_order_mark)
+        columns = batched_export_filter_columns(builder.exec_columns(view_context))
+        buffer = +""
+        byte_order_mark = options[:byte_order_mark]
+        buffer << byte_order_mark if batch_page == 1 && byte_order_mark
+        if batch_page == 1 && options.fetch(:column_names, true)
+          header_line = columns.map do |column|
+            ActiveAdmin::Sanitizer.sanitize(builder.send(:encode, column.name, options))
+          end
+          buffer << CSV.generate_line(header_line, **csv_options)
+        end
+        paginated_export_rows(batch_page, page: page) do |resource|
+          row = builder.build_row(resource, columns, options)
+          row = apply_export_macros(row, columns, resource)
+          buffer << CSV.generate_line(row, **csv_options)
+        end
+        buffer
+      end
+
+      def batched_json_chunk(batch_page, page: nil)
+        builder = active_admin_config.csv_builder
+        options = builder.options
+        columns = batched_export_filter_columns(builder.exec_columns(view_context))
+        names = columns.map(&:name)
+        rows = []
+        paginated_export_rows(batch_page, page: page) do |resource|
+          row = apply_export_macros(builder.build_row(resource, columns, options), columns, resource)
+          rows << names.zip(row).to_h
+        end
+        rows.to_json
+      end
+
+      def batched_xml_chunk(batch_page, page: nil)
+        builder = active_admin_config.csv_builder
+        options = builder.options
+        columns = batched_export_filter_columns(builder.exec_columns(view_context))
+        xml = Builder::XmlMarkup.new(indent: 0)
+        paginated_export_rows(batch_page, page: page) do |resource|
+          row = apply_export_macros(builder.build_row(resource, columns, options), columns, resource)
+          xml.batch do
+            xml.record do
+              columns.each_with_index do |column, index|
+                xml.field("name" => column.name) { xml.text!(row[index].to_s) }
+              end
+            end
+          end
+        end
+        xml.target!
+      end
+
+      def apply_export_macros(row, columns, resource)
+        ExportMacroResolver.apply(
+          row: row,
+          columns: columns,
+          resource: resource,
+          resource_settings: active_admin_config.batched_export_settings,
+          registry: merged_macro_registry
+        )
+      end
+
+      def merged_macro_registry
+        BatchedExport.config.registered_macros.merge(ExportMacroCatalog.global_registry)
+      end
+
+      def paginated_export_rows(batch_page, page: nil)
+        (page || page_relation(batch_page)).each do |resource|
+          yield apply_decorator(resource)
+        end
+      end
+
+      def page_relation(page)
+        collection = find_collection(except: [:pagination])
+        includes_list = active_admin_config.batched_export_includes
+        collection = collection.includes(includes_list) if includes_list.present?
+        paginate(collection, page, effective_batch_size)
+      end
+
+      def effective_batch_size
+        active_admin_config.batched_export_effective_batch_size
+      end
+
+      def assign_batched_export_workspace_extras!(export_format)
+        @batched_export_preview = batched_export_meta(export_format)
+        @batched_export_csv_columns =
+          if active_admin_config.batched_export_column_selection?
+            batched_export_csv_column_metadata
+          else
+            []
+          end
+        summary_chain = scoped_collection
+        summary_chain = apply_authorization_scope(summary_chain)
+        ransack_search = summary_chain.ransack(
+          params[:q] || {},
+          auth_object: active_admin_authorization
+        )
+        @batched_export_active_filters =
+          ActiveAdmin::Filters::Active.new(active_admin_config, ransack_search)
+        @batched_export_sort_description = batched_export_sort_description
+        @batched_export_large_export = @batched_export_preview[:large_export]
+      end
+
+      def batched_export_sort_description
+        order_param = params[:order].presence || active_admin_config.sort_order
+        clause = ActiveAdmin::OrderClause.new(active_admin_config, order_param)
+        return order_param.to_s.tr("_", " ").strip.presence || "—" unless clause.valid?
+
+        attribute = active_admin_config.resource_class.human_attribute_name(clause.field)
+        direction =
+          if clause.order == "desc"
+            I18n.t("active_admin.batched_export_page.sort_descending")
+          else
+            I18n.t("active_admin.batched_export_page.sort_ascending")
+          end
+        "#{attribute} — #{direction}"
+      end
+
+      def batched_export_csv_column_metadata
+        builder = active_admin_config.csv_builder
+        columns = builder.exec_columns(view_context)
+        columns.each_with_index.map do |column, index|
+          {index: index, label: column.name}
+        end
+      end
+
+      def batched_export_selected_indices
+        raw = params[:export_columns].presence || params[:export_column_indices]
+        return [] if raw.blank?
+
+        Array(raw).filter_map { |value| Integer(value, exception: false) }.select { |index| index >= 0 }
+      end
+
+      def batched_export_filter_columns(columns)
+        indices = batched_export_selected_indices
+        return columns if indices.empty?
+
+        resolved = indices.filter_map { |index| columns[index] }
+        resolved.presence || columns
+      end
+    end
+  end
+end

data/lib/activeadmin/batched_export/engine.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module BatchedExport
+    class Engine < ::Rails::Engine
+      engine_name "activeadmin_batched_export"
+
+      initializer "activeadmin_batched_export.load_lib" do
+        require "activeadmin/batched_export"
+        require "activeadmin/batched_export/styles"
+        require "activeadmin/batched_export/export_macro_catalog"
+        require "activeadmin/batched_export/export_macro_resolver"
+        require "activeadmin/batched_export/configuration"
+        require "activeadmin/batched_export/resource_extension"
+        require "activeadmin/batched_export/controller_methods"
+        require "activeadmin/batched_export/install"
+      end
+
+      initializer "activeadmin_batched_export.assets" do |app|
+        assets_path = root.join("app/assets")
+        app.config.importmap.cache_sweepers << assets_path.join("controllers") if app.config.respond_to?(:importmap)
+      end
+
+      initializer "activeadmin_batched_export.importmap", after: :load_config_initializers do
+        next unless Rails.application.respond_to?(:importmap) && Rails.application.importmap
+
+        pin_controller = proc do |importmap|
+          importmap.pin "controllers/activeadmin_batched_export/batched_export_controller",
+            to: "activeadmin_batched_export/batched_export_controller.js"
+        end
+
+        Rails.application.importmap.draw(&pin_controller)
+        ActiveAdmin.importmap.draw(&pin_controller) if defined?(ActiveAdmin)
+      end
+
+      initializer "activeadmin_batched_export.i18n" do
+        I18n.load_path << root.join("config/locales/activeadmin_batched_export.en.yml")
+      end
+
+      config.to_prepare do
+        ActiveAdmin::BatchedExport::Install.call if defined?(ActiveAdmin)
+      end
+    end
+  end
+end

data/lib/activeadmin/batched_export/export_macro_catalog.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "digest"
+require "active_support/core_ext/object/blank"
+
+module ActiveAdmin
+  module BatchedExport
+    class ExportMacroCatalog
+      class UnknownMacroError < KeyError; end
+
+      def self.register(name, callable, registry: nil)
+        key = name.to_sym
+        raise ArgumentError, "macro must respond to :call" unless callable.respond_to?(:call)
+
+        target = registry || global_registry
+        target[key] = callable
+      end
+
+      def self.fetch(name, registry: nil)
+        key = name.to_sym
+        target = registry || global_registry
+        target[key] || built_ins[key] || raise(UnknownMacroError, "unknown export macro: #{name}")
+      end
+
+      def self.resolve(name, registry: nil)
+        macro = name
+        return macro if macro.respond_to?(:call)
+
+        fetch(macro, registry: registry)
+      end
+
+      def self.global_registry
+        @global_registry ||= {}
+      end
+
+      def self.built_ins
+        @built_ins ||= {
+          mask_email: lambda { |value, _record, _column|
+            next nil if value.blank?
+
+            local, domain = value.to_s.split("@", 2)
+            next "[redacted]" if local.blank? || domain.blank?
+
+            visible = local[0, 2] || ""
+            "#{visible}***@#{domain}"
+          },
+          mask_phone: lambda { |value, _record, _column|
+            next nil if value.blank?
+
+            digits = value.to_s.gsub(/\D/, "")
+            next "[redacted]" if digits.length < 4
+
+            "#{"*" * (digits.length - 4)}#{digits[-4, 4]}"
+          },
+          truncate_middle: lambda { |value, _record, _column|
+            next nil if value.blank?
+
+            text = value.to_s
+            next text if text.length <= 8
+
+            "#{text[0, 3]}…#{text[-3, 3]}"
+          },
+          hash_identifier: lambda { |value, _record, _column|
+            next nil if value.blank?
+
+            Digest::SHA256.hexdigest(value.to_s)[0, 12]
+          },
+          redact: lambda { |_value, _record, _column|
+            "[redacted]"
+          }
+        }.freeze
+      end
+
+      private_class_method :built_ins
+    end
+  end
+end

data/lib/activeadmin/batched_export/export_macro_resolver.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module BatchedExport
+    class ExportMacroResolver
+      MAX_MACROS = 50
+
+      def self.apply(row:, columns:, resource:, resource_settings:, registry:)
+        new(
+          row: row,
+          columns: columns,
+          resource: resource,
+          resource_settings: resource_settings,
+          registry: registry
+        ).apply
+      end
+
+      def initialize(row:, columns:, resource:, resource_settings:, registry:)
+        @row = row.dup
+        @columns = columns
+        @resource = resource
+        @resource_settings = resource_settings || {}
+        @registry = registry
+        @resource_macros = normalize_macro_map(@resource_settings[:macros] || @resource_settings["macros"])
+      end
+
+      def apply
+        @columns.each_with_index do |column, index|
+          macro = macro_for(column)
+          next if macro.nil?
+
+          @row[index] = macro.call(@row[index], @resource, column)
+        end
+        @row
+      end
+
+      private
+
+      def macro_for(column)
+        explicit = column.options[:macro] if column.respond_to?(:options)
+        return resolve_macro(explicit) unless explicit.nil?
+
+        keys = macro_lookup_keys(column)
+        keys.each do |key|
+          mapped = @resource_macros[key]
+          return resolve_macro(mapped) unless mapped.nil?
+        end
+
+        nil
+      end
+
+      def macro_lookup_keys(column)
+        keys = []
+        keys << column.data if column.respond_to?(:data) && column.data.is_a?(Symbol)
+        keys << column.name if column.respond_to?(:name)
+        keys.map { |key| key.to_s.downcase.tr(" ", "_") }.uniq
+      end
+
+      def normalize_macro_map(macros)
+        return {} unless macros.is_a?(Hash)
+        raise ArgumentError, "too many export macros" if macros.size > MAX_MACROS
+
+        macros.each_with_object({}) do |(key, value), normalized|
+          normalized[key.to_s.downcase.tr(" ", "_")] = value
+        end
+      end
+
+      def resolve_macro(macro)
+        ExportMacroCatalog.resolve(macro, registry: @registry)
+      end
+    end
+  end
+end