paper_trail-human 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a4ca501d7c667357906931d0e4460948d92dcd0b8595f1162b0a25d980650c72
+  data.tar.gz: 87e69c7b0461fcf423fece4f6f8f6471214861f0fd2300ad484795a3eacc19c6
+SHA512:
+  metadata.gz: d16233ba896c6f145177f3852b763aa7f8390cd12b68ae2077e2d9b7287e7cbb93d0944f940fafc77241161a5e5a0db764d160b75fde29338cc6e14143e14165
+  data.tar.gz: 342d5cdf3e9742e00bc58dab8ccfaca91b3a47e990d4dcfde4bc4b184c54e1a7f42af4830548f74bc444b2fd5ffcc8213759255950bc205049522595d9b4cdce

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## [0.3.0] - 2026-05-30
+
+### Added
+- `:date` resolver with configurable `strftime` format
+- `:number` resolver with currency, percentage, and custom formatting
+- `item_name` resolver for human-readable record identifiers
+- Output formats: `as: :text`, `as: :markdown`, `as: :html` (XSS-safe)
+- `PaperTrail::Human.timeline` for grouping versions by day/week/month/year
+- `after_format` hook for post-processing results
+- CONTRIBUTING.md with architecture guide
+
+### Changed
+- Minimum Ruby version raised to 3.1 (dropped 2.7, 3.0)
+- Minimum Rails version raised to 6.1 (dropped 5.2, 6.0)
+- Minimum PaperTrail version raised to 12.0
+- CI matrix: Ruby 3.1–3.4 × Rails 6.1–8.0 × PaperTrail 12–15
+- README rewritten as full English documentation
+
+### Removed
+- Support for Ruby < 3.1, Rails < 6.1, PaperTrail < 12
+
+## [0.2.0] - 2026-05-30
+
+### Added
+- I18n integration for field names via `activerecord.attributes`
+- I18n event label translation with locale files (en, pt-BR)
+- Rails native enum support (`from_model:` option)
+- `:text` resolver for long text truncation with diff stats
+- `only:` and `except:` field filters
+- Batch loading of relations (N+1 prevention)
+- Event-specific fields (create omits previous_value, destroy omits value)
+- Warning when `object_changes` column is missing
+
+### Fixed
+- `Psych::DisallowedClass` with YAML serializer (added ActiveSupport::TimeWithZone)
+- Field names now remove `_id` suffix automatically
+
+## [0.1.0] - 2026-05-29
+
+### Added
+- Initial release
+- Core presenter with hexagonal architecture
+- Resolvers: relation, enum, boolean, custom
+- Configuration DSL with per-model field registration
+- Thread-safe configuration
+- Support for JSON, YAML, and jsonb object_changes
+- Whodunnit resolver callback
+- Configurable ignored fields
+- RuboCop configuration (rubocop-rspec, rubocop-performance)
+- CI with GitHub Actions matrix (Ruby 3.0-3.3 × Rails 6.1-8.0)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Gabriel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,435 @@
+# paper_trail-human
+
+[![Gem Version](https://badge.fury.io/rb/paper_trail-human.svg)](https://rubygems.org/gems/paper_trail-human)
+[![CI](https://github.com/gabrielrumiranda/paper_trail-human/actions/workflows/ci.yml/badge.svg)](https://github.com/gabrielrumiranda/paper_trail-human/actions)
+
+Transforms `PaperTrail::Version` records into structured, human-readable hashes ready for UI display — audit logs, timelines, activity feeds.
+
+Resolves foreign keys to names, translates enums and constants, formats dates and numbers, and accepts custom transformations via lambda.
+
+## Table of Contents
+
+- [1. Introduction](#1-introduction)
+  - [1a. Compatibility](#1a-compatibility)
+  - [1b. Installation](#1b-installation)
+  - [1c. Quick Start](#1c-quick-start)
+- [2. Configuration](#2-configuration)
+  - [2a. Global Options](#2a-global-options)
+  - [2b. Per-Model Fields](#2b-per-model-fields)
+  - [2c. Item Name](#2c-item-name)
+  - [2d. After Format Hook](#2d-after-format-hook)
+- [3. Resolvers](#3-resolvers)
+  - [3a. Relation](#3a-relation)
+  - [3b. Enum](#3b-enum)
+  - [3c. Boolean](#3c-boolean)
+  - [3d. Custom](#3d-custom)
+  - [3e. Text](#3e-text)
+  - [3f. Date](#3f-date)
+  - [3g. Number](#3g-number)
+- [4. Formatting](#4-formatting)
+  - [4a. Single Version](#4a-single-version)
+  - [4b. Collection](#4b-collection)
+  - [4c. Filtering Fields](#4c-filtering-fields)
+  - [4d. Output Formats](#4d-output-formats)
+- [5. Timeline](#5-timeline)
+- [6. I18n](#6-i18n)
+  - [6a. Field Names](#6a-field-names)
+  - [6b. Event Labels](#6b-event-labels)
+- [7. Architecture](#7-architecture)
+- [8. Requirements](#8-requirements)
+- [9. Contributing](#9-contributing)
+- [10. License](#10-license)
+
+## 1. Introduction
+
+### 1a. Compatibility
+
+| paper_trail-human | ruby    | activerecord | paper_trail |
+|-------------------|---------|--------------|-------------|
+| 0.3.x             | >= 3.1  | >= 6.1       | >= 12.0     |
+| 0.2.x             | >= 3.0  | >= 6.1       | >= 12.0     |
+| 0.1.x             | >= 2.7  | >= 5.2       | >= 9.0      |
+
+**CI matrix (0.3.x):**
+
+| Rails | PaperTrail | Ruby              |
+|-------|-----------|-------------------|
+| 6.1   | ~> 12.0   | 3.1, 3.2, 3.3, 3.4 |
+| 7.0   | ~> 13.0   | 3.1, 3.2, 3.3, 3.4 |
+| 7.1   | ~> 14.0   | 3.1, 3.2, 3.3, 3.4 |
+| 7.2   | ~> 15.0   | 3.1, 3.2, 3.3, 3.4 |
+| 8.0   | ~> 15.0   | 3.2, 3.3, 3.4      |
+
+### 1b. Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "paper_trail-human"
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate paper_trail:human:install
+```
+
+The generator creates an initializer at `config/initializers/paper_trail_human.rb`.
+
+**Important:** This gem reads from the `object_changes` column. If your versions table doesn't have it, add it:
+
+```bash
+rails generate paper_trail:install --with-changes
+rails db:migrate
+```
+
+### 1c. Quick Start
+
+```ruby
+# config/initializers/paper_trail_human.rb
+PaperTrail::Human.configure do |config|
+  config.whodunnit_resolver = ->(id) { User.find_by(id: id)&.name }
+end
+
+# Anywhere in your app
+PaperTrail::Human.format(version)
+# => {
+#   user: "John",
+#   event: "update",
+#   model: "User",
+#   item_id: 1,
+#   created_at: 2026-05-29 12:00:00,
+#   fields: [
+#     { field: "Name", previous_value: "John", value: "John Smith" },
+#     { field: "Company", previous_value: "Acme", value: "Globex" }
+#   ]
+# }
+```
+
+## 2. Configuration
+
+### 2a. Global Options
+
+```ruby
+PaperTrail::Human.configure do |config|
+  # Resolve whodunnit IDs to names (default: nil, returns raw ID)
+  config.whodunnit_resolver = ->(id) { User.find_by(id: id)&.name }
+
+  # Fields to exclude from output (default: %w[id created_at updated_at])
+  config.ignored_fields = %w[id created_at updated_at]
+
+  # Custom field name resolver (default: nil, uses I18n then humanize)
+  config.field_name_resolver = ->(field, model) { ... }
+
+  # Translate event names via I18n (default: false)
+  config.translate_events = true
+
+  # Post-processing hook (default: nil)
+  config.after_format = ->(result, version) { result }
+end
+```
+
+### 2b. Per-Model Fields
+
+```ruby
+PaperTrail::Human.configure do |config|
+  config.register "User" do |m|
+    m.field :role, :enum, class_name: "UserRole", method: :label
+    m.field :company_id, :relation, class_name: "Company", attribute: :name
+    m.field :active, :boolean, true_label: "Active", false_label: "Inactive"
+    m.field :bio, :text, max_length: 100, show_diff_stats: true
+    m.field :due_date, :date, format: "%d/%m/%Y"
+    m.field :salary, :number, format: :currency, unit: "R$"
+    m.field :score, :custom, resolve: ->(v) { "#{v} points" }
+  end
+end
+```
+
+### 2c. Item Name
+
+Adds a human-readable identifier for the record to the output:
+
+```ruby
+config.register "User" do |m|
+  m.item_name :name
+  # or with a lambda:
+  m.item_name ->(version) { "User ##{version.item_id}" }
+end
+
+PaperTrail::Human.format(version)[:item_name]
+# => "João Silva"
+```
+
+The `item_name` key is only present when the record exists and the attribute is configured.
+
+### 2d. After Format Hook
+
+Post-process every formatted result:
+
+```ruby
+config.after_format = ->(result, version) {
+  result[:record_url] = "/#{result[:model].tableize}/#{result[:item_id]}"
+  result
+}
+```
+
+The lambda receives the formatted hash and the original `PaperTrail::Version`, and must return the hash.
+
+## 3. Resolvers
+
+### 3a. Relation
+
+Resolves a foreign key to an attribute of the associated model.
+
+```ruby
+m.field :company_id, :relation, class_name: "Company", attribute: :name
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `class_name:` | The associated model class | required |
+| `attribute:` | Attribute to display | `:name` |
+
+In batch mode (`format_collection`), relations are preloaded to prevent N+1 queries.
+
+### 3b. Enum
+
+Resolves enum values to human labels.
+
+```ruby
+# With a class that responds to a method
+m.field :role, :enum, class_name: "UserRole", method: :label
+
+# With a static mapping
+m.field :status, :enum, mapping: { "active" => "Active", "inactive" => "Inactive" }
+
+# With Rails native enum
+m.field :role, :enum, from_model: "User"
+m.field :role, :enum, from_model: "User", labels: { admin: "Administrator" }
+```
+
+| Option | Description |
+|--------|-------------|
+| `class_name:` + `method:` | Calls `ClassName.method(value)` |
+| `mapping:` | Static hash lookup |
+| `from_model:` | Reads from `Model.defined_enums` |
+| `labels:` | Custom labels for `from_model` |
+
+### 3c. Boolean
+
+Custom labels for boolean fields:
+
+```ruby
+m.field :active, :boolean, true_label: "Active", false_label: "Inactive"
+```
+
+### 3d. Custom
+
+Arbitrary transformation via lambda:
+
+```ruby
+m.field :score, :custom, resolve: ->(value) { "#{value} points" }
+```
+
+### 3e. Text
+
+Truncates long text fields:
+
+```ruby
+m.field :body, :text, max_length: 100, show_diff_stats: true
+# => "Lorem ipsum dolor sit amet..." (250 chars)
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `max_length:` | Maximum characters before truncation | `80` |
+| `show_diff_stats:` | Append total char count | `false` |
+
+### 3f. Date
+
+Formats date/time values:
+
+```ruby
+m.field :due_date, :date, format: "%d/%m/%Y"
+# => "30/05/2026"
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `format:` | `strftime` format string | `"%Y-%m-%d"` |
+
+Accepts `Date`, `Time`, `DateTime`, and parseable strings.
+
+### 3g. Number
+
+Formats numeric values:
+
+```ruby
+m.field :amount, :number, format: :currency, unit: "R$"
+# => "R$ 1,500.99"
+
+m.field :rate, :number, format: :percentage
+# => "85.50%"
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `format:` | `:default`, `:currency`, `:percentage` | `:default` |
+| `unit:` | Currency symbol (for `:currency`) | `nil` |
+| `precision:` | Decimal places | `2` |
+| `delimiter:` | Thousands separator | `","` |
+| `separator:` | Decimal separator | `"."` |
+
+## 4. Formatting
+
+### 4a. Single Version
+
+```ruby
+PaperTrail::Human.format(version)
+```
+
+Returns a hash with keys: `user`, `event`, `model`, `item_id`, `created_at`, `fields`, and optionally `item_name`.
+
+Event-specific behavior:
+- **create**: fields omit `previous_value`
+- **update**: fields include both `previous_value` and `value`
+- **destroy**: fields omit `value`
+
+### 4b. Collection
+
+```ruby
+PaperTrail::Human.format_collection(user.versions)
+```
+
+Same as `format` but for multiple versions. Relations are batch-loaded to prevent N+1 queries.
+
+### 4c. Filtering Fields
+
+```ruby
+PaperTrail::Human.format(version, only: [:name, :email])
+PaperTrail::Human.format(version, except: [:password_digest])
+```
+
+### 4d. Output Formats
+
+By default, methods return hashes. Use `as:` for string output:
+
+```ruby
+PaperTrail::Human.format(version, as: :text)
+# => "Updated User#1 by John at 2026-05-30\n  • Name: Old → New"
+
+PaperTrail::Human.format(version, as: :markdown)
+# => Markdown with header and table
+
+PaperTrail::Human.format(version, as: :html)
+# => HTML div with table (XSS-safe, escapes entities)
+```
+
+Available formats: `:text`, `:markdown`, `:html`.
+
+Works with both `format` and `format_collection`.
+
+## 5. Timeline
+
+Group versions by time period:
+
+```ruby
+PaperTrail::Human.timeline(user.versions, group_by: :day)
+# => {
+#   "2026-05-28" => [{ user: ..., fields: [...] }, ...],
+#   "2026-05-30" => [{ user: ..., fields: [...] }]
+# }
+```
+
+| `group_by` | Format | Example |
+|-----------|--------|---------|
+| `:day` | `%Y-%m-%d` | `"2026-05-30"` |
+| `:week` | `%G-W%V` | `"2026-W22"` |
+| `:month` | `%Y-%m` | `"2026-05"` |
+| `:year` | `%Y` | `"2026"` |
+
+Supports `only:` and `except:` filters.
+
+## 6. I18n
+
+### 6a. Field Names
+
+Field names are resolved in this order:
+
+1. Custom `field_name_resolver` lambda (if configured)
+2. `I18n.t("activerecord.attributes.model_name.field_name")` (if I18n available)
+3. Automatic humanization (removes `_id` suffix, titleizes)
+
+Example: `company_id` → looks up `activerecord.attributes.user.company_id` → falls back to `"Company"`.
+
+### 6b. Event Labels
+
+Enable translated event labels:
+
+```ruby
+config.translate_events = true
+```
+
+The gem includes locale files for `en` and `pt-BR`. Add your own:
+
+```yaml
+# config/locales/paper_trail_human.en.yml
+en:
+  paper_trail_human:
+    events:
+      create: "Created"
+      update: "Updated"
+      destroy: "Destroyed"
+```
+
+```yaml
+# config/locales/paper_trail_human.pt-BR.yml
+pt-BR:
+  paper_trail_human:
+    events:
+      create: "Criação"
+      update: "Atualização"
+      destroy: "Exclusão"
+```
+
+## 7. Architecture
+
+Hexagonal (Ports & Adapters):
+
+```
+┌─────────────────────────────────────────────┐
+│                   Core                       │
+│  ChangeExtractor · FieldFormatter            │
+│  EventTranslator · Presenter                 │
+│  BatchPresenter  · Timeline                  │
+├─────────────────────────────────────────────┤
+│                   Ports                       │
+│  Resolver (interface)                        │
+├─────────────────────────────────────────────┤
+│                  Adapters                     │
+│  Resolvers: Relation, Enum, Boolean,         │
+│             Custom, Text, Date, Number       │
+│  Formatters: Text, Markdown, Html            │
+└─────────────────────────────────────────────┘
+```
+
+- **Core** — pure formatting logic, no external dependencies
+- **Ports** — `Resolver` interface that every adapter implements
+- **Adapters** — concrete implementations for resolving values and formatting output
+
+The gem has zero dependencies beyond `activerecord` and `paper_trail`. The Railtie is optional — it works in non-Rails apps (Sinatra, Hanami, etc).
+
+## 8. Requirements
+
+- Ruby >= 3.1
+- Rails >= 6.1 (or standalone ActiveRecord)
+- PaperTrail >= 12.0
+
+## 9. Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on setting up the development environment, running tests, and submitting pull requests.
+
+## 10. License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/config/locales/en.yml

@@ -0,0 +1,6 @@
+en:
+  paper_trail_human:
+    events:
+      create: "Created"
+      update: "Updated"
+      destroy: "Destroyed"

data/config/locales/pt-BR.yml

@@ -0,0 +1,6 @@
+pt-BR:
+  paper_trail_human:
+    events:
+      create: "Criação"
+      update: "Atualização"
+      destroy: "Exclusão"

data/lib/generators/paper_trail/human/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module PaperTrail
+  module Human
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a PaperTrail::Human initializer'
+
+      def copy_initializer
+        template 'initializer.rb', 'config/initializers/paper_trail_human.rb'
+      end
+    end
+  end
+end

data/lib/generators/paper_trail/human/templates/initializer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+PaperTrail::Human.configure do |config|
+  # Resolver quem fez a alteração (recebe whodunnit ID, retorna nome)
+  # config.whodunnit_resolver = ->(id) { User.find_by(id: id)&.name }
+
+  # Campos ignorados globalmente (default: id, created_at, updated_at)
+  # config.ignored_fields = %w[id created_at updated_at]
+
+  # Resolver customizado para nomes de campos (usa I18n/human_attribute_name)
+  # config.field_name_resolver = ->(field_name, item_type) {
+  #   item_type.constantize.human_attribute_name(field_name)
+  # }
+
+  # Configuração por model:
+  #
+  # config.register 'User' do |m|
+  #   m.field :role, :enum, class_name: 'UserRole', method: :label
+  #   m.field :company_id, :relation, class_name: 'Company', attribute: :name
+  #   m.field :active, :boolean, true_label: 'Ativo', false_label: 'Inativo'
+  #   m.field :score, :custom, resolve: ->(v) { "#{v} pontos" }
+  # end
+end

data/lib/paper_trail/human/adapters/formatters/html.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Adapters
+      module Formatters
+        class Html
+          def call(result)
+            [
+              %(<div class="paper-trail-version">),
+              "  <p>#{header(result)}</p>",
+              '  <table>',
+              '    <thead><tr><th>Field</th><th>Previous</th><th>Current</th></tr></thead>',
+              '    <tbody>',
+              *result[:fields].map { |f| table_row(f) },
+              '    </tbody>',
+              '  </table>',
+              '</div>'
+            ].join("\n")
+          end
+
+          private
+
+          def header(result)
+            event = escape(result[:event])
+            model = escape(result[:model])
+            user = escape(result[:user].to_s)
+            "<strong>#{event}</strong> #{model}##{result[:item_id]} by #{user}"
+          end
+
+          def table_row(field)
+            prev = escape(field.fetch(:previous_value, '—').to_s)
+            curr = escape(field.fetch(:value, '—').to_s)
+            "      <tr><td>#{escape(field[:field])}</td><td>#{prev}</td><td>#{curr}</td></tr>"
+          end
+
+          def escape(str)
+            str.gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;').gsub('"', '&quot;').gsub("'", '&#39;')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/adapters/formatters/markdown.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Adapters
+      module Formatters
+        class Markdown
+          def call(result)
+            lines = [header(result), '']
+            lines << '| Field | Previous | Current |'
+            lines << '|-------|----------|---------|'
+            result[:fields].each { |f| lines << table_row(f) }
+            lines.join("\n")
+          end
+
+          private
+
+          def header(result)
+            "**#{result[:event]}** `#{result[:model]}##{result[:item_id]}` " \
+              "by #{result[:user]} at #{result[:created_at]}"
+          end
+
+          def table_row(field)
+            prev = field.fetch(:previous_value, '—')
+            curr = field.fetch(:value, '—')
+            "| #{field[:field]} | #{prev} | #{curr} |"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Adapters
+      module Formatters
+        class Text
+          def call(result)
+            lines = [header(result)]
+            result[:fields].each { |f| lines << field_line(f) }
+            lines.join("\n")
+          end
+
+          private
+
+          def header(result)
+            "#{result[:event]} #{result[:model]}##{result[:item_id]} by #{result[:user]} at #{result[:created_at]}"
+          end
+
+          def field_line(field)
+            if field.key?(:previous_value) && field.key?(:value)
+              "  • #{field[:field]}: #{field[:previous_value]} → #{field[:value]}"
+            elsif field.key?(:value)
+              "  • #{field[:field]}: #{field[:value]}"
+            else
+              "  • #{field[:field]}: #{field[:previous_value]} (removed)"
+            end
+          end
+        end
+      end
+    end
+  end
+end