paper_trail_history 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a439b37d64e8ecaeec57377d5db127935c4b64954f7b2471f935b6c80b8ef777
+  data.tar.gz: 2c246306235393b7ff3dd2c98935535b943b1eba296cc03073d4c3187a19f763
+SHA512:
+  metadata.gz: 2f85826967ac33827d1ada925b772a12d5bb5cd7becb799bfc3d2f74fe97abf5c10d6ad45c3087d155d4021f58592649927f8a99eb3dbdb24c3800b87d1500f4
+  data.tar.gz: b407e86259a9e18083f36f9759a34f7b2430c52c101fcf43f6c2dee713c6c47814bd2db7c6d8e9d7b96fbdac7ee244ae0e079c293dcf4e32bce6d8d55e943138

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Benjamin Deutscher
+
+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,188 @@
+# PaperTrailHistory
+
+A Rails engine providing a comprehensive web interface for managing PaperTrail versions. View, search, filter, and restore audit trail records with an intuitive Bootstrap-styled interface.
+
+## Features
+
+- **List All Trackable Models**: Discover all models in your application that use `has_paper_trail`
+- **Browse Version History**: View all versions for specific models or individual records
+- **Advanced Filtering**: Filter versions by event type, user, date range, and search content
+- **Detailed Version View**: See exactly what changed in each version with before/after comparisons
+- **Restore Functionality**: Safely restore records to previous versions with confirmation
+- **Responsive Design**: Clean, Bootstrap-styled interface that works on all devices
+- **Breadcrumb Navigation**: Easy navigation between models, records, and versions
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "paper_trail_history"
+```
+
+And then execute:
+```bash
+$ bundle install
+```
+
+Mount the engine in your routes file (`config/routes.rb`):
+
+```ruby
+Rails.application.routes.draw do
+  mount PaperTrailHistory::Engine, at: '/revisions'
+  # your other routes...
+end
+```
+
+## Prerequisites
+
+This engine requires:
+- Rails >= 8.0.2
+- PaperTrail >= 15.0 (configured with `has_paper_trail` in your models)
+
+Make sure you have PaperTrail properly configured in your Rails application before using this engine.
+
+## Usage
+
+After mounting the engine, navigate to `/revisions` (or whatever path you chose) in your browser to access the interface.
+
+### Main Features
+
+1. **Models Overview** (`/revisions/models`)
+   - Lists all models with paper trail enabled
+   - Shows version counts for each model
+   - Quick access to recent versions
+
+2. **Model Versions** (`/revisions/models/:model_name/versions`)
+   - View all versions for a specific model
+   - Filter by event type, user, date range
+   - Search within version content
+   - Pagination support
+
+3. **Record Versions** (`/revisions/models/:model_name/:record_id/versions`)
+   - View version history for a specific record
+   - See current record state vs historical versions
+
+4. **Version Details** (`/revisions/versions/:id`)
+   - Detailed view of what changed in a specific version
+   - Side-by-side comparison of old vs new values
+   - Restore functionality with confirmation
+
+### Filtering and Search
+
+The interface provides several ways to filter and search versions:
+
+- **Event Type**: Filter by create, update, or destroy events
+- **User**: Filter by who made the changes (whodunnit)
+- **Date Range**: Show versions within specific date ranges
+- **Content Search**: Search within the stored object changes
+
+### Restoring Versions
+
+You can restore any version (except create events) by:
+
+1. Navigate to the version details page
+2. Click "Restore This Version"
+3. Confirm the restoration
+
+**Note**: Restoring a version will create a new version entry, so you can always see the restoration in the audit trail.
+
+## Development
+
+### Setting up the Test Environment
+
+```bash
+# Install dependencies
+bundle install
+
+# Set up test database with sample data
+cd test/dummy
+bundle exec rails db:create RAILS_ENV=test
+bundle exec rails db:migrate RAILS_ENV=test
+bundle exec rails db:seed RAILS_ENV=test
+cd ../..
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run integration tests only
+bundle exec rake test:integration
+
+# Run specific test file
+bundle exec ruby -I test test/models/paper_trail_history/trackable_model_test.rb
+
+# Run with verbose output
+bundle exec rake test TESTOPTS="-v"
+
+# Run code quality checks
+bundle exec rubocop
+```
+
+### Testing Different Components
+
+```bash
+# Test models only
+bundle exec rake test TEST="test/models/**/*_test.rb"
+
+# Test controllers only  
+bundle exec rake test TEST="test/controllers/**/*_test.rb"
+
+# Test integration features
+bundle exec rake test TEST="test/integration/**/*_test.rb"
+```
+
+### Using the Dummy Application
+
+The `test/dummy` directory contains a full Rails application with sample models and data for testing:
+
+```bash
+# Start the development server
+cd test/dummy && bundle exec rails server
+
+# Visit the engine interface
+open http://localhost:3000/paper_trail_history
+```
+
+The dummy app includes:
+- **User, Post, Comment models** - Standard PaperTrail setup
+- **Product model** - Custom version table (`ProductVersion`) 
+- **Rich seed data** - Various change types, workflows, and scenarios
+- **I18n translations** - Proper model pluralization
+
+### Testing Against Multiple Rails Versions
+
+For comprehensive compatibility testing, use the provided Gemfiles:
+
+```bash
+# Test against Rails 7.1
+BUNDLE_GEMFILE=gemfiles/rails_7.1.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_7.1.gemfile bundle exec rake test
+
+# Test against Rails 8.0
+BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile bundle install  
+BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile bundle exec rake test
+
+# Test against Rails main branch
+BUNDLE_GEMFILE=gemfiles/rails_main.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_main.gemfile bundle exec rake test
+```
+
+### Continuous Integration
+
+The project uses GitHub Actions to test against multiple Ruby and Rails versions. See `.github/workflows/ci.yml` for the full matrix configuration.
+
+## Contributing
+
+1. Fork the project
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+# Load test tasks
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+namespace :test do
+  Rake::TestTask.new(:integration) do |t|
+    t.libs << 'test'
+    t.pattern = 'test/integration/**/*_test.rb'
+    t.verbose = false
+  end
+end
+
+task default: :test

data/app/assets/stylesheets/paper_trail_history/application.css

@@ -0,0 +1,93 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */
+
+/* Git-style diff formatting */
+.diff-container {
+  font-family: 'SFMono-Regular', 'Monaco', 'Inconsolata', 'Roboto Mono', monospace;
+  font-size: 0.9rem;
+}
+
+.diff-section {
+  border: 1px solid #e1e4e8;
+  border-radius: 6px;
+  overflow: hidden;
+}
+
+.diff-header {
+  background-color: #f6f8fa;
+  padding: 8px 12px;
+  border-bottom: 1px solid #e1e4e8;
+  font-weight: 600;
+  color: #586069;
+}
+
+.diff-content {
+  background-color: #fff;
+}
+
+.diff-line {
+  display: flex;
+  align-items: flex-start;
+  padding: 2px 0;
+  line-height: 1.45;
+  position: relative;
+}
+
+.diff-line code {
+  background: none;
+  border: none;
+  padding: 4px 8px;
+  margin: 0;
+  flex: 1;
+  font-size: 0.85rem;
+  white-space: pre-wrap;
+  word-break: break-all;
+}
+
+.diff-marker {
+  display: inline-block;
+  width: 20px;
+  text-align: center;
+  font-weight: bold;
+  flex-shrink: 0;
+  font-size: 0.9rem;
+  padding: 4px 0;
+  user-select: none;
+}
+
+.diff-removed {
+  background-color: #ffeef0;
+  border-left: 3px solid #f85149;
+}
+
+.diff-removed .diff-marker {
+  color: #f85149;
+  background-color: #ffdddf;
+}
+
+.diff-added {
+  background-color: #e6ffed;
+  border-left: 3px solid #2ea043;
+}
+
+.diff-added .diff-marker {
+  color: #2ea043;
+  background-color: #ccf2d4;
+}
+
+.diff-line:hover {
+  background-color: rgba(0, 0, 0, 0.05);
+}

data/app/controllers/paper_trail_history/application_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module PaperTrailHistory
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/paper_trail_history/models_controller.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module PaperTrailHistory
+  # Controller for managing trackable model operations and displaying version histories
+  class ModelsController < ApplicationController
+    def index
+      @trackable_models = TrackableModel.all_with_counts
+    end
+
+    def show
+      @trackable_model = TrackableModel.find(params[:name])
+
+      unless @trackable_model
+        redirect_to models_path, alert: t('paper_trail_history.errors.model_not_found', model_name: params[:name])
+        return
+      end
+
+      @recent_versions = VersionDecorator.decorate_collection(
+        @trackable_model.recent_versions(20)
+      )
+    end
+
+    def versions
+      @trackable_model = find_trackable_model_or_redirect
+      return unless @trackable_model
+
+      load_versions_data
+      load_filter_options
+    end
+
+    private
+
+    def find_trackable_model_or_redirect
+      trackable_model = TrackableModel.find(params[:name])
+      unless trackable_model
+        redirect_to models_path, alert: t('paper_trail_history.errors.model_not_found', model_name: params[:name])
+        return nil
+      end
+      trackable_model
+    end
+
+    def load_versions_data
+      @versions = VersionService.for_model(params[:name], filter_params)
+      @versions = @versions.includes(:item)
+      @decorated_versions = VersionDecorator.decorate_collection(@versions)
+    end
+
+    def load_filter_options
+      @available_events = VersionService.available_events(params[:name])
+      @available_whodunnits = VersionService.unique_whodunnits(params[:name])
+    end
+
+    def filter_params
+      params.permit(:event, :whodunnit, :from_date, :to_date, :search, :page)
+    end
+  end
+end

data/app/controllers/paper_trail_history/records_controller.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PaperTrailHistory
+  # Controller for managing individual record operations and their version histories
+  class RecordsController < ApplicationController
+    def show
+      @trackable_model = find_trackable_model_or_redirect
+      return unless @trackable_model
+
+      load_record_data
+      load_recent_versions
+    end
+
+    def versions
+      @trackable_model = find_trackable_model_or_redirect
+      return unless @trackable_model
+
+      load_record_data
+      load_versions_with_filters
+      load_available_events
+    end
+
+    private
+
+    def find_trackable_model_or_redirect
+      trackable_model = TrackableModel.find(params[:model_name])
+      unless trackable_model
+        redirect_to models_path, alert: t('paper_trail_history.errors.model_not_found', model_name: params[:model_name])
+        return nil
+      end
+      trackable_model
+    end
+
+    def load_record_data
+      @record = @trackable_model.klass.find_by(id: params[:record_id])
+      @record_id = params[:record_id]
+    end
+
+    def load_recent_versions
+      @recent_versions = VersionDecorator.decorate_collection(
+        VersionService.for_record(params[:model_name], params[:record_id], {}).limit(10)
+      )
+    end
+
+    def load_versions_with_filters
+      @versions = VersionService.for_record(params[:model_name], params[:record_id], filter_params)
+      @decorated_versions = VersionDecorator.decorate_collection(@versions)
+    end
+
+    def load_available_events
+      @available_events = VersionService.available_events(params[:model_name])
+    end
+
+    def filter_params
+      params.permit(:event, :from_date, :to_date, :page)
+    end
+  end
+end

data/app/controllers/paper_trail_history/versions_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PaperTrailHistory
+  # Controller for managing version operations like viewing and restoring specific versions
+  class VersionsController < ApplicationController
+    before_action :find_version, only: %i[show restore]
+
+    def show
+      @decorated_version = VersionDecorator.decorate(@version)
+      @trackable_model = TrackableModel.find(@version.item_type)
+    end
+
+    def restore
+      result = VersionService.restore_version(@version.id)
+
+      if result[:success]
+        redirect_back fallback_location: version_path(@version),
+                      notice: result[:message]
+      else
+        redirect_back fallback_location: version_path(@version),
+                      alert: t('paper_trail_history.errors.restore_failed', error: result[:error])
+      end
+    end
+
+    private
+
+    def find_version
+      @version = PaperTrail::Version.find(params[:id])
+    rescue ActiveRecord::RecordNotFound
+      redirect_to root_path, alert: t('paper_trail_history.errors.version_not_found')
+    end
+  end
+end

data/app/helpers/paper_trail_history/application_helper.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module PaperTrailHistory
+  # Helper module providing utility methods for PaperTrailHistory views
+  module ApplicationHelper
+  end
+end

data/app/jobs/paper_trail_history/application_job.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module PaperTrailHistory
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/paper_trail_history/application_mailer.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PaperTrailHistory
+  # Base mailer class for PaperTrailHistory email notifications
+  class ApplicationMailer < ActionMailer::Base
+    default from: 'from@example.com'
+    layout 'mailer'
+  end
+end

data/app/models/paper_trail_history/application_record.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module PaperTrailHistory
+  # Base ActiveRecord class for PaperTrailHistory models
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/paper_trail_history/trackable_model.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module PaperTrailHistory
+  # Model wrapper for trackable ActiveRecord classes with PaperTrail versioning
+  class TrackableModel
+    attr_reader :name, :klass, :cached_version_count
+
+    def initialize(klass, cached_version_count = nil)
+      @klass = klass
+      @name = klass.name
+      @cached_version_count = cached_version_count
+    end
+
+    def self.all
+      return @all_models if defined?(@all_models) && @all_models
+
+      Rails.application.eager_load!
+
+      # Use a Set to ensure uniqueness by class name
+      trackable_classes = {}
+      ObjectSpace.each_object(Class) do |klass|
+        next unless klass < ActiveRecord::Base
+        next if klass.abstract_class?
+        next unless klass.included_modules.include?(PaperTrail::Model::InstanceMethods)
+
+        # Only keep one instance per class name to avoid duplicates
+        trackable_classes[klass.name] = new(klass)
+      end
+
+      @all_models = trackable_classes.values.sort_by(&:name)
+    end
+
+    def self.all_with_counts
+      models = all
+      return models if models.empty?
+
+      count_cache = build_count_cache(models)
+      models_with_cached_counts(models, count_cache)
+    end
+
+    def self.build_count_cache(models)
+      models_by_version_class = models.group_by(&:version_class)
+      count_cache = {}
+      populate_count_cache(models_by_version_class, count_cache)
+      count_cache
+    end
+
+    def self.populate_count_cache(models_by_version_class, count_cache)
+      models_by_version_class.each do |version_class, models_for_class|
+        counts = fetch_version_counts(version_class, models_for_class)
+        cache_counts_for_models(models_for_class, counts, count_cache)
+      end
+    end
+
+    def self.fetch_version_counts(version_class, models_for_class)
+      item_types = models_for_class.map(&:item_type_for_versions)
+      version_class.where(item_type: item_types).group(:item_type).count
+    end
+
+    def self.cache_counts_for_models(models_for_class, counts, count_cache)
+      models_for_class.each do |model|
+        count_cache[model.name] = counts[model.item_type_for_versions] || 0
+      end
+    end
+
+    def self.models_with_cached_counts(models, count_cache)
+      models.map { |model| new(model.klass, count_cache[model.name]) }
+    end
+
+    def self.find(model_name)
+      all.find { |model| model.name == model_name }
+    end
+
+    # Clear cached models (useful in development when adding new trackable models)
+    def self.clear_cache!
+      @all_models = nil
+    end
+
+    def versions
+      version_class.where(item_type: item_type_for_versions)
+    end
+
+    def item_type_for_versions
+      # PaperTrail stores item_type as the class name, but let's be explicit
+      # and handle potential namespace issues
+      klass.name
+    end
+
+    def total_versions_count
+      # Use cached count if available (from all_with_counts), otherwise query
+      @cached_version_count || versions.count
+    end
+
+    def recent_versions(limit = 10)
+      versions.order(created_at: :desc).limit(limit)
+    end
+
+    def version_class
+      @version_class ||= klass.paper_trail.version_class || PaperTrail::Version
+    end
+
+    def version_table_name
+      version_class.table_name
+    end
+
+    delegate :table_name, to: :klass
+
+    def human_name
+      klass.model_name.human(count: 2)
+    end
+  end
+end