well_formed-paper_trail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9aa0be2c5bdb3f7c9f04d9e81ac7481fe76dd4ecb65b87aa559fb3a87ac666ba
+  data.tar.gz: 578dcf5c3f11f0cfd0b5c3c458710944d2250b7b8185c990649239680c5d1af8
+SHA512:
+  metadata.gz: 74a4f2bbe4f5a581a15a72e56bb195c84cb473fe2f8d8c67bc8b1c12d0c58017dca55959e0a84f040acafd96c0aafe57075bfd5adddb2eb4a598f589cb89a7d4
+  data.tar.gz: 26785c4bd0b2029fd0f82ec64c6c1389af96b616194c001a2231018bab7dc99fa60b8d40659d217fbf6d5b03bca8ae26132182a5025d6c0a6a13cf54a8187405

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/README.md

@@ -0,0 +1,106 @@
+# well_formed-paper_trail
+
+[PaperTrail](https://github.com/paper-trail-gem/paper_trail) versioning integration for [WellFormed](https://github.com/bmorrall/well_formed) form objects.
+
+Automatically sets `PaperTrail.request.whodunnit` to the form's `user` around every `save` and `perform`, so version records are attributed to the correct user without any controller wiring.
+
+## Installation
+
+```bash
+bundle add well_formed-paper_trail
+```
+
+## Usage
+
+Require the gem in your application:
+
+```ruby
+require "well_formed-paper_trail"
+```
+
+`WellFormed::PaperTrail` is automatically included into all WellFormed forms — no `include` required. With PaperTrail configured on your models, versions are immediately attributed to the form's `user`:
+
+```ruby
+class UpdateArticleForm < WellFormed::ResourceForm
+  resource_alias :article
+
+  attribute :title, :string
+  attribute :body,  :string
+
+  validates :title, presence: true
+end
+
+form = UpdateArticleForm.new(article, current_user, article_params)
+form.save
+# => PaperTrail::Version created with whodunnit: current_user.id.to_s
+```
+
+Works for `ActionForm` too — any model changes made inside `perform` are attributed correctly:
+
+```ruby
+class PublishArticleForm < WellFormed::ActionForm
+  resource_alias :article
+
+  def perform
+    article.publish!   # triggers a PaperTrail version attributed to user
+  end
+end
+```
+
+### Custom whodunnit
+
+By default, `whodunnit` is set to `user&.id&.to_s`. There are two ways to override this.
+
+#### Global default
+
+Set a global proc in an initializer. It receives the form's `user` as its argument:
+
+```ruby
+# config/initializers/well_formed_paper_trail.rb
+WellFormed::PaperTrail.whodunnit = ->(user) { user&.email }
+```
+
+#### Per-form override
+
+Use `paper_trail_whodunnit` to override on a specific form class. The block is evaluated in the context of the form instance, so all form attributes and helpers (including `user`) are available:
+
+```ruby
+class UpdateArticleForm < WellFormed::ResourceForm
+  paper_trail_whodunnit { user.email }
+end
+```
+
+```ruby
+class AdminUpdateForm < WellFormed::ResourceForm
+  paper_trail_whodunnit { "admin:#{user.id}" }
+end
+```
+
+The per-form macro takes precedence over the global config. It is also inherited by subclasses and can be overridden per subclass:
+
+```ruby
+class BaseForm < WellFormed::ResourceForm
+  paper_trail_whodunnit { user.email }
+end
+
+class AuditedForm < BaseForm
+  paper_trail_whodunnit { "#{user.role}:#{user.id}" }  # overrides parent
+end
+```
+
+The priority order is: **per-form macro → global config → `user&.id&.to_s`**.
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `WellFormed::PaperTrail.whodunnit = ->(user) { ... }` | Global default — proc receives `user`, return value used as `whodunnit` |
+| `paper_trail_whodunnit { ... }` | Per-form macro — block evaluated on the form instance, takes precedence over global config. Inherits from superclass. |
+
+## How it works
+
+`whodunnit` is set via `PaperTrail.request(whodunnit:) { ... }` inside an `around_save` callback (for `ResourceForm` and `Struct`) or an `around_perform` callback (for `ActionForm`). This is the thread-safe, block-scoped API recommended by PaperTrail — the previous `whodunnit` value is always restored after the block exits, even if an exception is raised.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new(:rubocop)

data/lib/well_formed/paper_trail/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module WellFormed
+  module PaperTrail
+    VERSION = "0.1.0"
+  end
+end

data/lib/well_formed/paper_trail.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module WellFormed
+  module PaperTrail
+    @whodunnit = nil
+
+    class << self
+      # Global default whodunnit proc, used when no per-form +paper_trail_whodunnit+ is set.
+      # The proc receives the form's +user+ as its argument.
+      #
+      #   WellFormed::PaperTrail.whodunnit = ->(user) { user&.email }
+      #
+      attr_accessor :whodunnit
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.set_callback(:save, :around, :_with_paper_trail) if base.respond_to?(:_save_callbacks)
+      base.set_callback(:perform, :around, :_with_paper_trail) if base.respond_to?(:_perform_callbacks)
+    end
+
+    module ClassMethods
+      # Override the whodunnit value set on PaperTrail.request during save/perform.
+      # The block is evaluated in the context of the form instance, so form attributes
+      # and helpers (including +user+) are available.
+      #
+      #   paper_trail_whodunnit { user.email }
+      #   paper_trail_whodunnit { "admin:#{user.id}" }
+      #
+      # Defaults to +user&.id&.to_s+ when not set.
+      def paper_trail_whodunnit(&block)
+        @_paper_trail_whodunnit = block
+      end
+
+      def _paper_trail_whodunnit_proc
+        return @_paper_trail_whodunnit if defined?(@_paper_trail_whodunnit)
+
+        superclass._paper_trail_whodunnit_proc if superclass.respond_to?(:_paper_trail_whodunnit_proc)
+      end
+    end
+
+    private
+
+    def _with_paper_trail
+      whodunnit = if (proc = self.class._paper_trail_whodunnit_proc)
+        instance_exec(&proc)
+      elsif (global = WellFormed::PaperTrail.whodunnit)
+        global.call(user)
+      else
+        user&.id&.to_s
+      end
+      ::PaperTrail.request(whodunnit: whodunnit) { yield }
+    end
+  end
+end

data/lib/well_formed-paper_trail.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "well_formed"
+require "paper_trail"
+require_relative "well_formed/paper_trail/version"
+require_relative "well_formed/paper_trail"
+
+WellFormed::WithUser.register_extension(WellFormed::PaperTrail)

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: well_formed-paper_trail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ben Morrall
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: well_formed
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !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'
+email:
+- bemo56@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- README.md
+- Rakefile
+- lib/well_formed-paper_trail.rb
+- lib/well_formed/paper_trail.rb
+- lib/well_formed/paper_trail/version.rb
+homepage: https://github.com/bmorrall/well_formed
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: PaperTrail versioning integration for well_formed
+test_files: []