paper_trail-human 0.3.0

data/lib/paper_trail/human/adapters/resolvers/boolean.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Adapters
+      module Resolvers
+        class Boolean
+          include Ports::Resolver
+
+          def initialize(true_label: 'Yes', false_label: 'No', **)
+            @true_label = true_label
+            @false_label = false_label
+          end
+
+          def resolve(value)
+            value ? @true_label : @false_label
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/adapters/resolvers/custom.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Adapters
+      module Resolvers
+        class Custom
+          include Ports::Resolver
+
+          def initialize(resolve:, **)
+            @proc = resolve
+          end
+
+          def resolve(value)
+            @proc.call(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/adapters/resolvers/date.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Adapters
+      module Resolvers
+        class Date
+          include Ports::Resolver
+
+          def initialize(format: '%Y-%m-%d', **)
+            @format = format
+          end
+
+          def resolve(value)
+            date = parse_date(value)
+            return value unless date
+
+            date.strftime(@format)
+          rescue ArgumentError
+            value
+          end
+
+          private
+
+          def parse_date(value)
+            return value if value.respond_to?(:strftime)
+
+            ::Date.parse(value.to_s)
+          rescue ArgumentError, TypeError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/adapters/resolvers/enum.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Adapters
+      module Resolvers
+        class Enum
+          include Ports::Resolver
+
+          def initialize(class_name: nil, method: :label, mapping: nil, from_model: nil, **options)
+            @class_name = class_name || options[:class].to_s
+            @method = method
+            @mapping = mapping
+            @from_model = from_model
+            @field = options[:field]&.to_s
+            @labels = options[:labels]
+          end
+
+          def resolve(value)
+            return resolve_from_model(value) if @from_model
+            return @mapping[value] || value if @mapping
+
+            klass = Object.const_get(@class_name)
+            if klass.respond_to?(@method)
+              klass.public_send(@method, value) || value
+            else
+              value
+            end
+          rescue NameError
+            value
+          end
+
+          private
+
+          def resolve_from_model(value)
+            klass = Object.const_get(@from_model)
+            enum_mapping = klass.defined_enums[@field]
+            return value unless enum_mapping
+
+            key = enum_mapping.key(value) || enum_mapping.key(value.to_i)
+            return value unless key
+
+            return @labels[key.to_sym] || @labels[key.to_s] || humanize(key) if @labels
+
+            humanize(key)
+          rescue NameError
+            value
+          end
+
+          def humanize(str)
+            str.to_s.tr('_', ' ').then { |s| "#{s[0].upcase}#{s[1..]}" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/adapters/resolvers/number.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Adapters
+      module Resolvers
+        class Number
+          include Ports::Resolver
+
+          # rubocop:disable Metrics/ParameterLists
+          def initialize(format: :default, unit: nil, precision: 2, delimiter: ',', separator: '.', **)
+            # rubocop:enable Metrics/ParameterLists
+            @format = format
+            @unit = unit
+            @precision = precision
+            @delimiter = delimiter
+            @separator = separator
+          end
+
+          def resolve(value)
+            num = to_number(value)
+            return value unless num
+
+            case @format
+            when :currency then format_currency(num)
+            when :percentage then format_percentage(num)
+            else format_number(num)
+            end
+          end
+
+          private
+
+          def to_number(value)
+            return value if value.is_a?(Numeric)
+
+            Float(value)
+          rescue ArgumentError, TypeError
+            nil
+          end
+
+          def format_number(num)
+            int_part, dec_part = rounded(num).split('.')
+            int_with_delimiters = int_part.gsub(/(\d)(?=(\d{3})+(?!\d))/, "\\1#{@delimiter}")
+            dec_part ? "#{int_with_delimiters}#{@separator}#{dec_part}" : int_with_delimiters
+          end
+
+          def format_currency(num)
+            "#{@unit} #{format_number(num)}"
+          end
+
+          def format_percentage(num)
+            "#{format_number(num)}%"
+          end
+
+          def rounded(num)
+            format("%<n>.#{@precision}f", n: num)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/adapters/resolvers/relation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Adapters
+      module Resolvers
+        class Relation
+          include Ports::Resolver
+
+          def initialize(class_name: nil, attribute: :name, cache: nil, **options)
+            @class_name = class_name || options[:class].to_s
+            @attribute = attribute
+            @cache = cache || {}
+          end
+
+          def resolve(value)
+            return @cache[value] || @cache[value.to_i] || value if @cache.any?
+
+            klass = safe_const_get(@class_name)
+            return value unless klass
+
+            record = klass.find_by(id: value)
+            record&.public_send(@attribute) || value
+          end
+
+          private
+
+          def safe_const_get(name)
+            klass = Object.const_get(name)
+            return klass if defined?(ActiveRecord::Base) && klass < ActiveRecord::Base
+            return klass if klass.respond_to?(:find_by)
+
+            nil
+          rescue NameError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/adapters/resolvers/text.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Adapters
+      module Resolvers
+        class Text
+          include Ports::Resolver
+
+          DEFAULT_MAX_LENGTH = 80
+
+          def initialize(max_length: DEFAULT_MAX_LENGTH, show_diff_stats: false, **)
+            @max_length = max_length
+            @show_diff_stats = show_diff_stats
+          end
+
+          def resolve(value)
+            text = value.to_s
+            return text if text.length <= @max_length
+
+            truncated = "#{text[0, @max_length]}..."
+            truncated += " (#{text.length} chars)" if @show_diff_stats
+            truncated
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/configuration.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    class Configuration
+      DEFAULT_IGNORED_FIELDS = %w[id created_at updated_at].freeze
+
+      attr_accessor :whodunnit_resolver, :extend_version_model, :field_name_resolver,
+                    :translate_events, :after_format
+      attr_reader :ignored_fields
+
+      def initialize
+        @model_configs = {}
+        @ignored_fields = DEFAULT_IGNORED_FIELDS.dup
+        @whodunnit_resolver = nil
+        @field_name_resolver = nil
+        @translate_events = false
+        @extend_version_model = false
+        @after_format = nil
+        @mutex = Mutex.new
+      end
+
+      def ignored_fields=(fields)
+        @ignored_fields = Array(fields).map(&:to_s)
+      end
+
+      def register(model_name, &)
+        model_config = ModelConfig.new
+        yield(model_config)
+        @mutex.synchronize { @model_configs[model_name.to_s] = model_config.freeze }
+      end
+
+      def config_for(model_name)
+        @model_configs[model_name.to_s]
+      end
+
+      def resolve_whodunnit(id)
+        return id unless whodunnit_resolver
+
+        whodunnit_resolver.call(id)
+      end
+
+      def resolve_item_name(version)
+        model_config = config_for(version.item_type)
+        return nil unless model_config&.item_name_attribute
+
+        attr = model_config.item_name_attribute
+        return attr.call(version) if attr.respond_to?(:call)
+
+        item = find_item(version)
+        item&.public_send(attr)
+      rescue NoMethodError, ActiveRecord::RecordNotFound
+        nil
+      end
+
+      private
+
+      def find_item(version)
+        klass = Object.const_get(version.item_type)
+        klass.find_by(id: version.item_id)
+      rescue NameError
+        nil
+      end
+    end
+
+    class ModelConfig
+      attr_reader :fields, :item_name_attribute
+
+      def initialize
+        @fields = {}
+        @item_name_attribute = nil
+      end
+
+      def field(name, type, **options)
+        @fields[name.to_s] = { type: type, options: options }
+      end
+
+      def item_name(attribute_or_lambda)
+        @item_name_attribute = attribute_or_lambda
+      end
+
+      def freeze
+        @fields.freeze
+        super
+      end
+    end
+  end
+end

data/lib/paper_trail/human/core/batch_presenter.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Core
+      class BatchPresenter
+        def initialize(configuration)
+          @configuration = configuration
+          @change_extractor = ChangeExtractor.new
+        end
+
+        def call(versions, only: nil, except: nil)
+          versions_data = versions.map { |v| [v, @change_extractor.call(v)] }
+          preloaded = preload_relations(versions_data)
+
+          versions_data.map do |version, changes|
+            format_version(version, changes, preloaded, only: only, except: except)
+          end
+        end
+
+        private
+
+        def format_version(version, changes, preloaded, only: nil, except: nil)
+          model_config = @configuration.config_for(version.item_type)
+          formatter = FieldFormatter.new(
+            model_config,
+            version.item_type,
+            field_name_resolver: @configuration.field_name_resolver,
+            preloaded: preloaded
+          )
+
+          result = {
+            user: @configuration.resolve_whodunnit(version.whodunnit),
+            event: EventTranslator.call(version.event, translate: @configuration.translate_events),
+            model: version.item_type,
+            item_id: version.item_id,
+            created_at: version.created_at,
+            fields: build_fields(changes, formatter, version.event, only: only, except: except)
+          }
+
+          item_name = @configuration.resolve_item_name(version)
+          result[:item_name] = item_name if item_name
+
+          apply_after_format(result, version)
+        end
+
+        def build_fields(changes, formatter, event, only: nil, except: nil)
+          changes
+            .reject { |field, _| @configuration.ignored_fields.include?(field.to_s) }
+            .select { |field, _| filter_field?(field, only, except) }
+            .map { |field, values| format_field(formatter, field, values, event) }
+        end
+
+        def filter_field?(field, only, except)
+          field_s = field.to_s
+          return only.map(&:to_s).include?(field_s) if only
+
+          return !except.map(&:to_s).include?(field_s) if except
+
+          true
+        end
+
+        def format_field(formatter, field, values, event)
+          previous_value, new_value = Array(values)
+          result = formatter.call(field, previous_value, new_value)
+
+          case event
+          when 'create'
+            result.delete(:previous_value)
+          when 'destroy'
+            result.delete(:value)
+          end
+
+          result
+        end
+
+        def preload_relations(versions_data)
+          relation_fields = collect_relation_fields(versions_data)
+          return {} if relation_fields.empty?
+
+          relation_fields.each_with_object({}) do |(key, ids), cache|
+            class_name, attribute = key
+            cache[key] = load_records(class_name, attribute, ids)
+          end
+        end
+
+        def collect_relation_fields(versions_data)
+          result = Hash.new { |h, k| h[k] = Set.new }
+
+          versions_data.each do |version, changes|
+            collect_from_version(result, version, changes)
+          end
+
+          result
+        end
+
+        def collect_from_version(result, version, changes)
+          model_config = @configuration.config_for(version.item_type)
+          return unless model_config
+
+          changes.each do |field, values|
+            field_cfg = model_config.fields[field.to_s]
+            next unless field_cfg && field_cfg[:type] == :relation
+
+            key = relation_key(field_cfg)
+            Array(values).compact.each { |v| result[key].add(v) }
+          end
+        end
+
+        def relation_key(field_cfg)
+          class_name = field_cfg[:options][:class_name] || field_cfg[:options][:class].to_s
+          attribute = field_cfg[:options][:attribute] || :name
+          [class_name, attribute]
+        end
+
+        def load_records(class_name, attribute, ids)
+          klass = Object.const_get(class_name)
+          klass.where(id: ids.to_a).to_h do |record|
+            [record.id, record.public_send(attribute)]
+          end
+        rescue NameError
+          {}
+        end
+
+        def apply_after_format(result, version)
+          return result unless @configuration.after_format
+
+          @configuration.after_format.call(result, version)
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/core/change_extractor.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'json'
+require 'bigdecimal'
+
+module PaperTrail
+  module Human
+    module Core
+      class ChangeExtractor
+        YAML_PERMITTED_CLASSES = [Time, Date, DateTime, BigDecimal, Symbol].freeze
+
+        def call(version)
+          changes = extract_object_changes(version)
+          return changes if changes
+
+          warn_missing_object_changes(version) if version.event == 'update'
+          infer_from_object(version)
+        end
+
+        private
+
+        def warn_missing_object_changes(version)
+          return if @warned
+
+          @warned = true
+          message = "[paper_trail-human] Version ##{version.id} (update) has no object_changes. " \
+                    'Add the object_changes column to your versions table for full update tracking.'
+          if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+            Rails.logger.warn(message)
+          else
+            warn message
+          end
+        end
+
+        def extract_object_changes(version)
+          return nil unless version.respond_to?(:object_changes) && version.object_changes
+
+          raw = version.object_changes
+          parse(raw)
+        end
+
+        def infer_from_object(version)
+          return {} unless version.respond_to?(:object) && version.object
+
+          parsed = parse(version.object)
+          return {} unless parsed.is_a?(Hash)
+
+          case version.event
+          when 'create'
+            parsed.transform_values { |v| [nil, v] }
+          when 'destroy'
+            parsed.transform_values { |v| [v, nil] }
+          else
+            {}
+          end
+        end
+
+        def parse(raw)
+          return raw if raw.is_a?(Hash)
+
+          JSON.parse(raw)
+        rescue JSON::ParserError
+          YAML.safe_load(raw, permitted_classes: yaml_permitted_classes, aliases: true)
+        rescue StandardError
+          {}
+        end
+
+        def yaml_permitted_classes
+          classes = YAML_PERMITTED_CLASSES.dup
+          classes << ActiveSupport::TimeWithZone if defined?(ActiveSupport::TimeWithZone)
+          classes << ActiveSupport::TimeZone if defined?(ActiveSupport::TimeZone)
+          classes << ActiveSupport::Duration if defined?(ActiveSupport::Duration)
+          classes
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/core/event_translator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Core
+      module EventTranslator
+        DEFAULT_LABELS = {
+          'create' => 'Created',
+          'update' => 'Updated',
+          'destroy' => 'Destroyed'
+        }.freeze
+
+        def self.call(event, translate:)
+          return event unless translate
+
+          return event unless defined?(I18n)
+
+          I18n.t("paper_trail_human.events.#{event}", default: nil) || DEFAULT_LABELS[event] || event
+        rescue I18n::InvalidLocale, I18n::InvalidLocaleData
+          DEFAULT_LABELS[event] || event
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/core/field_formatter.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Core
+      class FieldFormatter
+        RESOLVER_MAP = {
+          relation: 'PaperTrail::Human::Adapters::Resolvers::Relation',
+          enum: 'PaperTrail::Human::Adapters::Resolvers::Enum',
+          boolean: 'PaperTrail::Human::Adapters::Resolvers::Boolean',
+          custom: 'PaperTrail::Human::Adapters::Resolvers::Custom',
+          text: 'PaperTrail::Human::Adapters::Resolvers::Text',
+          date: 'PaperTrail::Human::Adapters::Resolvers::Date',
+          number: 'PaperTrail::Human::Adapters::Resolvers::Number'
+        }.freeze
+
+        def initialize(model_config, item_type, field_name_resolver: nil, preloaded: nil)
+          @model_config = model_config
+          @item_type = item_type
+          @field_name_resolver = field_name_resolver
+          @preloaded = preloaded || {}
+        end
+
+        def call(field_name, previous_value, new_value)
+          config = field_config(field_name)
+          resolver = build_resolver(config, field_name)
+
+          {
+            field: human_field_name(field_name),
+            previous_value: resolve_value(resolver, previous_value),
+            value: resolve_value(resolver, new_value)
+          }
+        end
+
+        private
+
+        def field_config(field_name)
+          return nil unless @model_config
+
+          @model_config.fields[field_name.to_s]
+        end
+
+        def build_resolver(config, field_name = nil)
+          return nil unless config
+
+          class_name = RESOLVER_MAP[config[:type]]
+          raise Error, "Unknown resolver type: #{config[:type]}" unless class_name
+
+          klass = Object.const_get(class_name)
+          opts = config[:options]
+          opts = opts.merge(cache: relation_cache(config)) if config[:type] == :relation
+          opts = opts.merge(field: field_name) if config[:type] == :enum && opts[:from_model]
+          klass.new(**opts)
+        end
+
+        def relation_cache(config)
+          class_name = config[:options][:class_name] || config[:options][:class].to_s
+          attribute = config[:options][:attribute] || :name
+          @preloaded[[class_name, attribute]] || {}
+        end
+
+        def resolve_value(resolver, value)
+          return value unless resolver
+          return value if value.nil?
+
+          resolver.resolve(value)
+        end
+
+        def human_field_name(field_name)
+          return @field_name_resolver.call(field_name, @item_type) if @field_name_resolver
+
+          i18n_field_name(field_name) || default_human_field_name(field_name)
+        end
+
+        def i18n_field_name(field_name)
+          return nil unless defined?(I18n)
+
+          model_key = @item_type.gsub('::', '/').gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                                .gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+          key = "activerecord.attributes.#{model_key}.#{field_name}"
+          I18n.t(key, default: nil)
+        rescue I18n::InvalidLocale, I18n::InvalidLocaleData
+          nil
+        end
+
+        def default_human_field_name(field_name)
+          field_name.to_s.delete_suffix('_id').tr('_', ' ').then { |s| "#{s[0].upcase}#{s[1..]}" }
+        end
+      end
+    end
+  end
+end