paper_trail-human 0.3.0

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Core
+      class Presenter
+        def initialize(configuration)
+          @configuration = configuration
+          @change_extractor = ChangeExtractor.new
+        end
+
+        def call(version, only: nil, except: nil)
+          changes = @change_extractor.call(version)
+          model_config = @configuration.config_for(version.item_type)
+          formatter = FieldFormatter.new(
+            model_config,
+            version.item_type,
+            field_name_resolver: @configuration.field_name_resolver
+          )
+
+          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
+
+        private
+
+        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 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/timeline.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Core
+      class Timeline
+        GROUPINGS = {
+          day: '%Y-%m-%d',
+          week: '%G-W%V',
+          month: '%Y-%m',
+          year: '%Y'
+        }.freeze
+
+        def initialize(configuration)
+          @configuration = configuration
+          @batch_presenter = BatchPresenter.new(configuration)
+        end
+
+        def call(versions, group_by: :day, only: nil, except: nil)
+          formatted = @batch_presenter.call(versions, only: only, except: except)
+          format_str = GROUPINGS.fetch(group_by.to_sym) do
+            raise Error, "Unknown group_by: #{group_by}. Available: #{GROUPINGS.keys.join(', ')}"
+          end
+
+          formatted.group_by { |r| r[:created_at].strftime(format_str) }
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/ports/resolver.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Ports
+      module Resolver
+        def resolve(value)
+          raise NotImplementedError, "#{self.class}#resolve must be implemented"
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/railtie.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    class Railtie < ::Rails::Railtie
+      initializer 'paper_trail_human.i18n' do
+        locale_path = File.expand_path('../../../config/locales/*.yml', __dir__)
+        I18n.load_path += Dir[locale_path]
+      end
+
+      initializer 'paper_trail_human.extend_version_model' do
+        ActiveSupport.on_load(:active_record) do
+          if PaperTrail::Human.configuration.extend_version_model
+            PaperTrail::Version.include(PaperTrail::Human::VersionExtension)
+          end
+        end
+      end
+    end
+
+    module VersionExtension
+      def formatted_log
+        PaperTrail::Human.format(self)
+      end
+    end
+  end
+end

data/lib/paper_trail/human/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    VERSION = '0.3.0'
+  end
+end

data/lib/paper_trail/human.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative 'human/version'
+require_relative 'human/configuration'
+require_relative 'human/core/change_extractor'
+require_relative 'human/core/field_formatter'
+require_relative 'human/core/event_translator'
+require_relative 'human/core/presenter'
+require_relative 'human/core/batch_presenter'
+require_relative 'human/core/timeline'
+require_relative 'human/ports/resolver'
+require_relative 'human/adapters/resolvers/relation'
+require_relative 'human/adapters/resolvers/enum'
+require_relative 'human/adapters/resolvers/boolean'
+require_relative 'human/adapters/resolvers/custom'
+require_relative 'human/adapters/resolvers/text'
+require_relative 'human/adapters/resolvers/date'
+require_relative 'human/adapters/resolvers/number'
+require_relative 'human/adapters/formatters/text'
+require_relative 'human/adapters/formatters/markdown'
+require_relative 'human/adapters/formatters/html'
+
+module PaperTrail
+  module Human
+    class Error < StandardError; end
+
+    MUTEX = Mutex.new
+    private_constant :MUTEX
+
+    FORMATTERS = {
+      text: Adapters::Formatters::Text,
+      markdown: Adapters::Formatters::Markdown,
+      html: Adapters::Formatters::Html
+    }.freeze
+    private_constant :FORMATTERS
+
+    class << self
+      def configuration
+        @configuration || MUTEX.synchronize { @configuration ||= Configuration.new }
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        MUTEX.synchronize { @configuration = Configuration.new }
+      end
+
+      def format(version, only: nil, except: nil, as: nil)
+        result = Core::Presenter.new(configuration).call(version, only: only, except: except)
+        as ? formatter(as).call(result) : result
+      end
+
+      def format_collection(versions, only: nil, except: nil, as: nil)
+        results = Core::BatchPresenter.new(configuration).call(versions, only: only, except: except)
+        as ? results.map { |r| formatter(as).call(r) } : results
+      end
+
+      private
+
+      def formatter(type)
+        klass = FORMATTERS[type.to_sym]
+        raise Error, "Unknown format: #{type}. Available: #{FORMATTERS.keys.join(', ')}" unless klass
+
+        klass.new
+      end
+
+      def timeline(versions, group_by: :day, only: nil, except: nil)
+        Core::Timeline.new(configuration).call(versions, group_by: group_by, only: only, except: except)
+      end
+    end
+  end
+end

data/lib/paper_trail-human.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'paper_trail'
+require_relative 'paper_trail/human'

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: paper_trail-human
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Gabriel
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: paper_trail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+description: Resolves foreign keys, enums, booleans and custom transformations from
+  PaperTrail::Version into structured, UI-ready hashes.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- config/locales/en.yml
+- config/locales/pt-BR.yml
+- lib/generators/paper_trail/human/install_generator.rb
+- lib/generators/paper_trail/human/templates/initializer.rb
+- lib/paper_trail-human.rb
+- lib/paper_trail/human.rb
+- lib/paper_trail/human/adapters/formatters/html.rb
+- lib/paper_trail/human/adapters/formatters/markdown.rb
+- lib/paper_trail/human/adapters/formatters/text.rb
+- lib/paper_trail/human/adapters/resolvers/boolean.rb
+- lib/paper_trail/human/adapters/resolvers/custom.rb
+- lib/paper_trail/human/adapters/resolvers/date.rb
+- lib/paper_trail/human/adapters/resolvers/enum.rb
+- lib/paper_trail/human/adapters/resolvers/number.rb
+- lib/paper_trail/human/adapters/resolvers/relation.rb
+- lib/paper_trail/human/adapters/resolvers/text.rb
+- lib/paper_trail/human/configuration.rb
+- lib/paper_trail/human/core/batch_presenter.rb
+- lib/paper_trail/human/core/change_extractor.rb
+- lib/paper_trail/human/core/event_translator.rb
+- lib/paper_trail/human/core/field_formatter.rb
+- lib/paper_trail/human/core/presenter.rb
+- lib/paper_trail/human/core/timeline.rb
+- lib/paper_trail/human/ports/resolver.rb
+- lib/paper_trail/human/railtie.rb
+- lib/paper_trail/human/version.rb
+homepage: https://github.com/gabrielrumiranda/paper_trail-human
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/gabrielrumiranda/paper_trail-human
+  source_code_uri: https://github.com/gabrielrumiranda/paper_trail-human
+  changelog_uri: https://github.com/gabrielrumiranda/paper_trail-human/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: Transforms PaperTrail versions into human-readable hashes for audit logs.
+test_files: []