well_formed 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a0261a88ec791fe146575065a052505be38ddf4b899eaec1ea6f69648ad9445
-  data.tar.gz: d5c21350691a1ad78f34b94aa4ff59d11c496d4a9d774c9b5ffda24c3c08ce84
+  metadata.gz: 76f1e5f45582808eddd2fd54df5c806ff9fdf7c98b2d48a733e0918c99404056
+  data.tar.gz: 868cb13f7192a529027b9809638f1b1b3e61bd9e53e647589be5917c2714ef25
 SHA512:
-  metadata.gz: b791b764fe96a550f25e6308a0e238016024e6edf2fe20c6085b5817b3212add43b45ec40296b65df5a2f3bbc14af523633f4537f7c4eaff7c61b85399c58f00
-  data.tar.gz: 45b73ded6c9643af05effd8e21926f64278185a128df497140d8aeb0384980ff24cdc9a9309f9e2066055d5f964be27005a80f990baa219db2adda9b2a1964da
+  metadata.gz: 05ea83dd04cce981118f8b3154d55a81b26919054cbee2877918630937c4f7540aa672a41a0ce9eabd8e8062d1387f6c8bab23421020d6007fc1923a38aa3cc4
+  data.tar.gz: 201011a76f89b5a84f689f91eddff8504ebb6e40b45cd5fd1d9bb28eb64718bd394e19c3d6f070607e6932d8055586e5cf4fe5e37b22e6074eb6ee575bb9da8c

data/.rubocop.yml

@@ -10,3 +10,9 @@ inherit_gem:
 AllCops:
   NewCops: enable
   SuggestExtensions: false
+
+Rails:
+  TargetRailsVersion: 7.2
+
+Rails/StrongParametersExpect:
+  Enabled: false

data/README.md

@@ -6,18 +6,16 @@ Form objects are compatible with `form_with` and Rails view helpers anywhere an
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add well_formed
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install well_formed
 ```
 
 ## Usage
@@ -850,6 +848,18 @@ form.user  # => current_user
 
 `ResourceForm`, `ActionForm`, and `Struct` are themselves implemented this way — they inherit from their Simple counterpart and prepend `WithUser`.
 
+## Plugins
+
+| Gem | Description |
+|-----|-------------|
+| [well_formed-pundit](gems/well_formed-pundit/README.md) | [Pundit](https://github.com/varvet/pundit) authorization — adds `authorize!`, `policy`, and `policy_scope` helpers to any WellFormed form |
+| [well_formed-paper_trail](gems/well_formed-paper_trail/README.md) | [PaperTrail](https://github.com/paper-trail-gem/paper_trail) versioning — automatically sets `whodunnit` to the form's `user` around every `save` and `perform`, with a `paper_trail_whodunnit` macro for custom values |
+| [well_formed-dry_types](gems/well_formed-dry_types/README.md) | [dry-types](https://dry-rb.org/gems/dry-types) coercion — declare typed attributes with `dry_attribute`; coercion runs before validation with configurable error messages |
+
+## See Also
+
+- **[Halitosis](https://github.com/bmorrall/halitosis)** — JSON serialization library for Rails APIs. Declare attributes, HAL-style links, permissions, and nested relationships on serializer classes; render resources and collections with built-in support for sorting, filtering, and pagination. Use `Halitosis::ErrorsSerializer` to serialize `ActiveModel::Errors` from a WellFormed form directly into a JSON:API-style errors response.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/gems/well_formed-dry_types/.rspec

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

data/gems/well_formed-dry_types/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "well_formed", path: "../../"
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "standard", "~> 1.3"
+gem "rubocop-rails", require: false

data/gems/well_formed-dry_types/README.md

@@ -0,0 +1,107 @@
+# well_formed-dry_types
+
+[dry-types](https://dry-rb.org/gems/dry-types) coercion integration for [WellFormed](https://github.com/bmorrall/well_formed) form objects.
+
+Declare typed attributes with `dry_attribute` and coercion runs automatically before validation — keeping your forms free of manual casting logic.
+
+## Installation
+
+```bash
+bundle add well_formed-dry_types
+```
+
+## Usage
+
+Require the gem in your application:
+
+```ruby
+require "well_formed-dry_types"
+```
+
+Include `WellFormed::DryTypes` in any form, then use `dry_attribute` in place of `attribute` for fields that need type coercion:
+
+```ruby
+module Types
+  include Dry.Types()
+end
+
+class CreateOrderForm < WellFormed::ResourceForm
+  include WellFormed::DryTypes
+
+  resource_alias :order
+
+  dry_attribute :quantity, Types::Params::Integer
+  dry_attribute :amount,   Types::Params::Decimal
+  dry_attribute :status,   Types::String.enum("pending", "confirmed")
+
+  validates :quantity, presence: true, numericality: {greater_than: 0}
+  validates :amount,   presence: true
+  validates :status,   presence: true
+end
+```
+
+Coercion runs before validation. If coercion fails, an error is added to the attribute and validation is skipped for that field:
+
+```ruby
+form = CreateOrderForm.new(order, current_user, {quantity: "abc", amount: "9.99", status: "pending"})
+form.valid?
+# => false
+form.errors[:quantity]
+# => ["must be Params::Integer"]  # dry-types error message
+```
+
+## Custom error messages
+
+Pass `message:` to override the default dry-types error message.
+
+#### I18n key
+
+```ruby
+dry_attribute :status, Types::String.enum("pending", "confirmed"), message: :inclusion
+```
+
+Passes the symbol to `errors.add`, which resolves it through your I18n translations.
+
+#### Literal string
+
+```ruby
+dry_attribute :amount, Types::Params::Decimal, message: "must be a number"
+```
+
+#### Default (no message option)
+
+```ruby
+dry_attribute :quantity, Types::Params::Integer
+```
+
+Falls back to the error message from dry-types itself.
+
+## Inheritance
+
+`_dry_attributes` merges up the superclass chain, so subclass forms inherit parent coercions and can add their own:
+
+```ruby
+class BaseOrderForm < WellFormed::ResourceForm
+  include WellFormed::DryTypes
+  dry_attribute :amount, Types::Params::Decimal
+end
+
+class CreateOrderForm < BaseOrderForm
+  dry_attribute :quantity, Types::Params::Integer
+  # inherits :amount coercion from BaseOrderForm
+end
+```
+
+## API
+
+| Class macro | Description |
+|---|---|
+| `dry_attribute(name, type, message: nil)` | Declares a coerced attribute. Coercion runs before validation via a `before_validate` callback. |
+
+## How it works
+
+When `WellFormed::DryTypes` is included, a `before_validate` callback (`_coerce_dry_attributes`) is registered. Before each validation run, every `dry_attribute` is coerced in declaration order. On `Dry::Types::CoercionError`, an error is added and the raw value is left in place. Subsequent validators can still run against the failing attribute (e.g. a `presence` check on a nil optional).
+
+## License
+
+MIT

data/gems/well_formed-dry_types/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/gems/well_formed-dry_types/lib/well_formed/dry_types/version.rb

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

data/gems/well_formed-dry_types/lib/well_formed/dry_types.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module WellFormed
+  module DryTypes
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.set_callback(:validate, :before, :_coerce_dry_attributes)
+    end
+
+    module ClassMethods
+      # Declares an attribute whose value is coerced via a dry-types type before
+      # validation runs. Any dry-types type is accepted, including constrained,
+      # optional, and sum types.
+      #
+      #   dry_attribute :amount,  Types::Params::Decimal
+      #   dry_attribute :status,  Types::String.enum("draft", "published")
+      #   dry_attribute :tags,    Types::Strict::Array.of(Types::Strict::String)
+      #   dry_attribute :score,   Types::Params::Integer.optional
+      #
+      # If coercion fails, an error is added to the attribute. Pass +message:+ to
+      # use a specific error message or I18n key instead of the dry-types error:
+      #
+      #   dry_attribute :status, Types::String.enum("draft", "published"), message: :inclusion
+      #   dry_attribute :amount, Types::Params::Decimal, message: "must be a number"
+      #
+      # Coercion runs before validation, so +validates :amount, presence: true+ will
+      # still fire for nil values on optional attributes.
+      def dry_attribute(name, type, message: nil)
+        _dry_attribute_registry[name] = {type: type, message: message}
+        attribute name
+      end
+
+      # Returns the merged dry-types attribute registry for this class and all ancestors.
+      def _dry_attributes
+        parent = superclass.respond_to?(:_dry_attributes) ? superclass._dry_attributes : {}
+        parent.merge(_dry_attribute_registry)
+      end
+
+      private
+
+      def _dry_attribute_registry
+        @_dry_attribute_registry ||= {}
+      end
+    end
+
+    private
+
+    def _coerce_dry_attributes
+      self.class._dry_attributes.each do |name, options|
+        coerced = options[:type].call(public_send(name))
+        public_send(:"#{name}=", coerced)
+      rescue ::Dry::Types::CoercionError => e
+        errors.add(name, options[:message] || e.message)
+      end
+    end
+  end
+end

data/gems/well_formed-dry_types/lib/well_formed-dry_types.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "well_formed"
+require "dry-types"
+require_relative "well_formed/dry_types/version"
+require_relative "well_formed/dry_types"
+
+WellFormed::Extensions.register_extension(WellFormed::DryTypes)

data/gems/well_formed-dry_types/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "well_formed-dry_types"
+
+module Types
+  include Dry.Types()
+end
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

data/gems/well_formed-dry_types/spec/well_formed/dry_types_spec.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+RSpec.describe WellFormed::DryTypes do
+  it "has a version number" do
+    expect(WellFormed::DryTypes::VERSION).not_to be_nil
+  end
+
+  describe "auto-include via Extensions" do
+    let(:form_class) do
+      stub_const("TestForm", Class.new(WellFormed::SimpleResource))
+    end
+
+    it "is included automatically in SimpleResource subclasses" do
+      expect(form_class.ancestors).to include(WellFormed::DryTypes)
+    end
+  end
+
+  describe "#dry_attribute coercion" do
+    let(:resource) { double("resource", save: true) }
+    let(:user) { double("user") }
+
+    let(:form_class) do
+      stub_const("CoercionForm", Class.new(WellFormed::ResourceForm) do
+        dry_attribute :amount, Types::Params::Decimal
+        dry_attribute :count, Types::Params::Integer
+      end)
+    end
+
+    it "coerces string params to the declared type before validation" do
+      form = form_class.new(resource, user, {amount: "42.5", count: "3"})
+      form.valid?
+
+      expect(form.amount).to eq(BigDecimal("42.5"))
+      expect(form.count).to eq(3)
+    end
+
+    it "stores the coerced value, not the raw string" do
+      form = form_class.new(resource, user, {amount: "10.00"})
+      form.valid?
+
+      expect(form.amount).to be_a(BigDecimal)
+    end
+
+    it "is valid when all coercions succeed" do
+      form = form_class.new(resource, user, {amount: "9.99", count: "1"})
+
+      expect(form).to be_valid
+    end
+  end
+
+  describe "coercion failures" do
+    let(:resource) { double("resource") }
+    let(:user) { double("user") }
+
+    let(:form_class) do
+      stub_const("FailureForm", Class.new(WellFormed::ResourceForm) do
+        dry_attribute :amount, Types::Params::Decimal
+        dry_attribute :count, Types::Params::Integer
+      end)
+    end
+
+    it "adds an error on the attribute when coercion fails" do
+      form = form_class.new(resource, user, {amount: "not-a-number"})
+      form.valid?
+
+      expect(form.errors[:amount]).to include('"not-a-number" cannot be coerced to decimal')
+    end
+
+    it "collects all coercion errors in a single valid? call" do
+      form = form_class.new(resource, user, {amount: "bad", count: "also-bad"})
+      form.valid?
+
+      expect(form.errors[:amount]).to include('"bad" cannot be coerced to decimal')
+      expect(form.errors[:count]).to include('invalid value for Integer(): "also-bad"')
+    end
+
+    it "leaves the raw value on the attribute when coercion fails" do
+      form = form_class.new(resource, user, {amount: "bad"})
+      form.valid?
+
+      expect(form.amount).to eq("bad")
+    end
+  end
+
+  describe "nil and optional values" do
+    let(:resource) { double("resource") }
+    let(:user) { double("user") }
+
+    it "passes nil through a strict type and raises a coercion error" do
+      form_class = stub_const("StrictNilForm", Class.new(WellFormed::ResourceForm) do
+        dry_attribute :amount, Types::Strict::Decimal
+      end)
+
+      form = form_class.new(resource, user, {amount: nil})
+      form.valid?
+
+      expect(form.errors[:amount]).not_to be_empty
+    end
+
+    it "accepts nil when the type is optional" do
+      form_class = stub_const("OptionalForm", Class.new(WellFormed::ResourceForm) do
+        dry_attribute :amount, Types::Params::Decimal.optional
+      end)
+
+      form = form_class.new(resource, user, {amount: nil})
+      form.valid?
+
+      expect(form.errors[:amount]).to be_empty
+      expect(form.amount).to be_nil
+    end
+  end
+
+  describe "message: option" do
+    let(:resource) { double("resource") }
+    let(:user) { double("user") }
+
+    it "uses an I18n symbol message on coercion failure" do
+      form_class = stub_const("SymbolMessageForm", Class.new(WellFormed::ResourceForm) do
+        dry_attribute :amount, Types::Params::Decimal, message: :invalid
+      end)
+
+      form = form_class.new(resource, user, {amount: "bad"})
+      form.valid?
+
+      expect(form.errors[:amount]).to include("is invalid")
+    end
+
+    it "uses a string message on coercion failure" do
+      form_class = stub_const("StringMessageForm", Class.new(WellFormed::ResourceForm) do
+        dry_attribute :amount, Types::Params::Decimal, message: "must be a number"
+      end)
+
+      form = form_class.new(resource, user, {amount: "bad"})
+      form.valid?
+
+      expect(form.errors[:amount]).to include("must be a number")
+    end
+
+    it "falls back to the dry-types error message when no message is given" do
+      form_class = stub_const("DefaultMessageForm", Class.new(WellFormed::ResourceForm) do
+        dry_attribute :amount, Types::Params::Decimal
+      end)
+
+      form = form_class.new(resource, user, {amount: "bad"})
+      form.valid?
+
+      expect(form.errors[:amount].first).not_to be_empty
+    end
+  end
+
+  describe "subclass inheritance" do
+    let(:resource) { double("resource", save: true) }
+    let(:user) { double("user") }
+
+    let(:parent_class) do
+      stub_const("DryParentForm", Class.new(WellFormed::ResourceForm) do
+        dry_attribute :amount, Types::Params::Decimal
+      end)
+    end
+
+    let(:child_class) do
+      stub_const("DryChildForm", Class.new(parent_class) do
+        dry_attribute :count, Types::Params::Integer
+      end)
+    end
+
+    it "child inherits the parent's dry_attribute declarations" do
+      form = child_class.new(resource, user, {amount: "5.0", count: "3"})
+      form.valid?
+
+      expect(form.amount).to eq(BigDecimal("5.0"))
+      expect(form.count).to eq(3)
+    end
+
+    it "parent is unaffected by the child's dry_attribute declarations" do
+      form = parent_class.new(resource, user, {amount: "5.0"})
+
+      expect(form).not_to respond_to(:count)
+    end
+
+    it "collects errors from both parent and child attributes" do
+      form = child_class.new(resource, user, {amount: "bad", count: "bad"})
+      form.valid?
+
+      expect(form.errors[:amount]).not_to be_empty
+      expect(form.errors[:count]).not_to be_empty
+    end
+  end
+
+  describe "constrained types" do
+    let(:resource) { double("resource") }
+    let(:user) { double("user") }
+
+    let(:form_class) do
+      stub_const("ConstrainedForm", Class.new(WellFormed::ResourceForm) do
+        dry_attribute :score, Types::Params::Integer.constrained(gteq: 0, lteq: 100)
+      end)
+    end
+
+    it "accepts a value within the constraint" do
+      form = form_class.new(resource, user, {score: "50"})
+      form.valid?
+
+      expect(form.errors[:score]).to be_empty
+      expect(form.score).to eq(50)
+    end
+
+    it "adds an error when the constraint is violated" do
+      form = form_class.new(resource, user, {score: "150"})
+      form.valid?
+
+      expect(form.errors[:score]).not_to be_empty
+    end
+  end
+end

data/gems/well_formed-dry_types/well_formed-dry_types.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "lib/well_formed/dry_types/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "well_formed-dry_types"
+  spec.version = WellFormed::DryTypes::VERSION
+  spec.authors = ["Ben Morrall"]
+  spec.email = ["bemo56@hotmail.com"]
+
+  spec.summary = "dry-types attribute coercion integration for well_formed"
+  spec.homepage = "https://github.com/bmorrall/well_formed"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  gemspec = File.basename(__FILE__)
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    ls.readlines("\x0", chomp: true).reject do |f|
+      (f == gemspec) ||
+        f.start_with?(*%w[spec/ .git Gemfile])
+    end
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "well_formed", ">= 0.1.0"
+  spec.add_dependency "dry-types", ">= 1.0"
+end

data/gems/well_formed-paper_trail/.rspec

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

data/gems/well_formed-paper_trail/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "well_formed", path: "../../"
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "standard", "~> 1.3"
+gem "rubocop-rails", require: false

data/gems/well_formed-paper_trail/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/gems/well_formed-paper_trail/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/gems/well_formed-paper_trail/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/gems/well_formed-paper_trail/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/gems/well_formed-paper_trail/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)

data/gems/well_formed-paper_trail/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "well_formed-paper_trail"
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

data/gems/well_formed-paper_trail/spec/well_formed/paper_trail_spec.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+RSpec.describe WellFormed::PaperTrail do
+  it "has a version number" do
+    expect(WellFormed::PaperTrail::VERSION).not_to be_nil
+  end
+
+  describe "auto-include via WithUser" do
+    let(:form_class) do
+      stub_const("TestForm", Class.new(WellFormed::ResourceForm) do
+        attribute :title, :string
+      end)
+    end
+
+    it "is included automatically when WithUser is prepended" do
+      expect(form_class.ancestors).to include(WellFormed::PaperTrail)
+    end
+  end
+
+  describe "ResourceForm — around save" do
+    let(:resource) { double("resource", save: true) }
+    let(:user) { double("user", id: 42) }
+
+    let(:form_class) do
+      stub_const("TestResourceForm", Class.new(WellFormed::ResourceForm) do
+        attribute :title, :string
+      end)
+    end
+
+    subject(:form) { form_class.new(resource, user) }
+
+    it "calls PaperTrail.request with whodunnit set to user.id.to_s" do
+      expect(::PaperTrail).to receive(:request).with(whodunnit: "42") do |**, &block|
+        block.call
+      end
+
+      form.save
+    end
+
+    it "wraps around resource.save so whodunnit is active during the save" do
+      order = []
+
+      allow(::PaperTrail).to receive(:request) do |whodunnit:, &block|
+        order << :paper_trail_start
+        block.call
+        order << :paper_trail_end
+      end
+      allow(resource).to receive(:save) do
+        order << :resource_save
+        true
+      end
+
+      form.save
+
+      expect(order).to eq([:paper_trail_start, :resource_save, :paper_trail_end])
+    end
+
+    context "when resource.save fails" do
+      before { allow(resource).to receive(:save).and_return(false) }
+
+      it "still calls PaperTrail.request" do
+        expect(::PaperTrail).to receive(:request).with(whodunnit: "42") do |**, &block|
+          block.call
+        end
+
+        form.save
+      end
+    end
+  end
+
+  describe "ActionForm — around perform" do
+    let(:user) { double("user", id: 7) }
+
+    let(:form_class) do
+      stub_const("TestActionForm", Class.new(WellFormed::ActionForm) do
+        def perform
+          # represents a transition, event dispatch, etc.
+        end
+      end)
+    end
+
+    subject(:form) { form_class.new(double("resource"), user) }
+
+    it "calls PaperTrail.request with whodunnit set to user.id.to_s" do
+      expect(::PaperTrail).to receive(:request).with(whodunnit: "7") do |**, &block|
+        block.call
+      end
+
+      form.submit
+    end
+
+    it "wraps around perform so whodunnit is active during the action" do
+      order = []
+
+      allow(::PaperTrail).to receive(:request) do |whodunnit:, &block|
+        order << :paper_trail_start
+        block.call
+        order << :paper_trail_end
+      end
+
+      form_class.before_perform { order << :before_perform }
+      form_class.after_perform { order << :after_perform }
+
+      form.submit
+
+      expect(order).to eq([:paper_trail_start, :before_perform, :after_perform, :paper_trail_end])
+    end
+  end
+
+  describe "global whodunnit config" do
+    let(:resource) { double("resource", save: true) }
+    let(:user) { double("user", id: 42, email: "alice@example.com") }
+
+    let(:form_class) do
+      stub_const("GlobalConfigForm", Class.new(WellFormed::ResourceForm) do
+        attribute :title, :string
+      end)
+    end
+
+    subject(:form) { form_class.new(resource, user) }
+
+    around do |example|
+      original = WellFormed::PaperTrail.whodunnit
+      example.run
+    ensure
+      WellFormed::PaperTrail.whodunnit = original
+    end
+
+    it "uses the global proc when no per-form macro is set" do
+      WellFormed::PaperTrail.whodunnit = ->(u) { u.email }
+
+      expect(::PaperTrail).to receive(:request).with(whodunnit: "alice@example.com") do |**, &block|
+        block.call
+      end
+
+      form.save
+    end
+
+    it "per-form macro takes precedence over the global config" do
+      WellFormed::PaperTrail.whodunnit = ->(u) { u.email }
+
+      form_class.paper_trail_whodunnit { "override" }
+
+      expect(::PaperTrail).to receive(:request).with(whodunnit: "override") do |**, &block|
+        block.call
+      end
+
+      form.save
+    end
+
+    it "falls back to user.id.to_s when global config is nil" do
+      WellFormed::PaperTrail.whodunnit = nil
+
+      expect(::PaperTrail).to receive(:request).with(whodunnit: "42") do |**, &block|
+        block.call
+      end
+
+      form.save
+    end
+  end
+
+  describe "#paper_trail_whodunnit macro" do
+    let(:resource) { double("resource", save: true) }
+    let(:user) { double("user", id: 42, email: "alice@example.com") }
+
+    context "with a custom whodunnit block" do
+      let(:form_class) do
+        stub_const("CustomWhodunnitForm", Class.new(WellFormed::ResourceForm) do
+          attribute :title, :string
+          paper_trail_whodunnit { user.email }
+        end)
+      end
+
+      subject(:form) { form_class.new(resource, user) }
+
+      it "uses the block's return value as whodunnit" do
+        expect(::PaperTrail).to receive(:request).with(whodunnit: "alice@example.com") do |**, &block|
+          block.call
+        end
+
+        form.save
+      end
+    end
+
+    context "when nil user" do
+      let(:form_class) do
+        stub_const("NilUserForm", Class.new(WellFormed::ResourceForm) do
+          attribute :title, :string
+        end)
+      end
+
+      subject(:form) { form_class.new(resource, nil) }
+
+      it "passes nil as whodunnit when user is nil" do
+        expect(::PaperTrail).to receive(:request).with(whodunnit: nil) do |**, &block|
+          block.call
+        end
+
+        form.save
+      end
+    end
+
+    context "with a subclass overriding the whodunnit" do
+      let(:parent_class) do
+        stub_const("ParentForm", Class.new(WellFormed::ResourceForm) do
+          attribute :title, :string
+          paper_trail_whodunnit { user.email }
+        end)
+      end
+
+      let(:child_class) do
+        stub_const("ChildForm", Class.new(parent_class) do
+          paper_trail_whodunnit { "admin:#{user.id}" }
+        end)
+      end
+
+      it "child uses its own whodunnit" do
+        form = child_class.new(resource, user)
+
+        expect(::PaperTrail).to receive(:request).with(whodunnit: "admin:42") do |**, &block|
+          block.call
+        end
+
+        form.save
+      end
+
+      it "parent still uses its own whodunnit" do
+        form = parent_class.new(resource, user)
+
+        expect(::PaperTrail).to receive(:request).with(whodunnit: "alice@example.com") do |**, &block|
+          block.call
+        end
+
+        form.save
+      end
+    end
+
+    context "with a subclass inheriting the parent whodunnit" do
+      let(:parent_class) do
+        stub_const("InheritParentForm", Class.new(WellFormed::ResourceForm) do
+          attribute :title, :string
+          paper_trail_whodunnit { user.email }
+        end)
+      end
+
+      let(:child_class) do
+        stub_const("InheritChildForm", Class.new(parent_class))
+      end
+
+      it "inherits the parent's whodunnit proc" do
+        form = child_class.new(resource, user)
+
+        expect(::PaperTrail).to receive(:request).with(whodunnit: "alice@example.com") do |**, &block|
+          block.call
+        end
+
+        form.save
+      end
+    end
+  end
+end

data/gems/well_formed-paper_trail/well_formed-paper_trail.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "lib/well_formed/paper_trail/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "well_formed-paper_trail"
+  spec.version = WellFormed::PaperTrail::VERSION
+  spec.authors = ["Ben Morrall"]
+  spec.email = ["bemo56@hotmail.com"]
+
+  spec.summary = "PaperTrail versioning integration for well_formed"
+  spec.homepage = "https://github.com/bmorrall/well_formed"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  gemspec = File.basename(__FILE__)
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    ls.readlines("\x0", chomp: true).reject do |f|
+      (f == gemspec) ||
+        f.start_with?(*%w[spec/ .git Gemfile])
+    end
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "well_formed", ">= 0.1.0"
+  spec.add_dependency "paper_trail", ">= 12.0"
+end

data/gems/well_formed-pundit/Gemfile

@@ -8,6 +8,5 @@ gem "well_formed", path: "../../"
 
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
-gem "activerecord", require: false
 gem "standard", "~> 1.3"
 gem "rubocop-rails", require: false

data/lib/well_formed/extensions.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module WellFormed
+  module Extensions
+    @extensions = []
+    @bases = []
+
+    def self.register_extension(mod)
+      @extensions << mod
+      @bases.each { |base| base.include(mod) }
+    end
+
+    def self.included(base)
+      @bases << base
+      @extensions.each { |mod| base.include(mod) }
+    end
+  end
+end

data/lib/well_formed/simple_action.rb

@@ -8,6 +8,7 @@ module WellFormed
     include AttributeAssignment
     include Performer
     include NestedAttributes
+    include Extensions
     prepend Initializer
     include RecordIdentity
   end

data/lib/well_formed/simple_resource.rb

@@ -9,6 +9,7 @@ module WellFormed
     include Transactional
     include Collections
     include NestedAttributes
+    include Extensions
     prepend Initializer
   end
 end

data/lib/well_formed/simple_struct.rb

@@ -17,6 +17,7 @@ module WellFormed
     include Translations
     include Persistence
     include NestedAttributes
+    include Extensions
     prepend Initializer
     prepend PoroInterface
 

data/lib/well_formed/transactional.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "active_record"
-
 module WellFormed
   module Transactional
     def self.included(base)
@@ -11,10 +9,21 @@ module WellFormed
 
     module ClassMethods
       def after_save_commit(*args, &block)
-        set_callback(:save_commit, :after, *args, &block)
+        require "active_record"
+        if block
+          set_callback(:save_commit, :after) do
+            ::ActiveRecord.after_all_transactions_commit { instance_exec(&block) }
+          end
+        else
+          method_name = args.shift
+          set_callback(:save_commit, :after, *args) do
+            ::ActiveRecord.after_all_transactions_commit { send(method_name) }
+          end
+        end
       end
 
       def save_within_transaction
+        require "active_record"
         set_callback(:save, :around) do |form, block|
           saved = false
           form.resource.class.transaction do
@@ -31,7 +40,7 @@ module WellFormed
 
     def save
       result = super
-      ::ActiveRecord.after_all_transactions_commit { run_callbacks(:save_commit) } if result
+      run_callbacks(:save_commit) if result
       result || false
     end
   end

data/lib/well_formed/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WellFormed
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/well_formed.rb

@@ -6,6 +6,7 @@ require_relative "well_formed/errors"
 require_relative "well_formed/railtie" if defined?(Rails::Railtie)
 
 module WellFormed
+  autoload :Extensions, "well_formed/extensions"
   autoload :Initializer, "well_formed/initializer"
   autoload :WithUser, "well_formed/with_user"
   autoload :AttributeAssignment, "well_formed/attribute_assignment"
@@ -34,5 +35,6 @@ module WellFormed
     base.include Collections
     base.include NestedAttributes
     base.prepend Initializer
+    base.include Extensions
   end
 end

data/sig/well_formed.rbs

@@ -38,12 +38,9 @@ module WellFormed
 
     attr_reader resource: ::WellFormed::_ActiveModelLike
 
-    def id: () -> untyped
-    def persisted?: () -> bool
     def new_record?: () -> bool
     def to_param: () -> ::String?
 
-    def save: () -> bool
     def save!: () -> bool
     def submit: () -> (::WellFormed::_ActiveModelLike | false)
     def submit!: () -> ::WellFormed::_ActiveModelLike
@@ -106,12 +103,9 @@ module WellFormed
 
     attr_reader resource: ::WellFormed::_ActiveModelLike
 
-    def id: () -> untyped
-    def persisted?: () -> bool
     def new_record?: () -> bool
     def to_param: () -> ::String?
 
-    def save: () -> bool
     def save!: () -> bool
     def submit: () -> (::WellFormed::_ActiveModelLike | false)
     def submit!: () -> ::WellFormed::_ActiveModelLike

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: well_formed
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Ben Morrall
@@ -41,6 +41,26 @@ files:
 - README.md
 - Rakefile
 - Steepfile
+- gems/well_formed-dry_types/.rspec
+- gems/well_formed-dry_types/Gemfile
+- gems/well_formed-dry_types/README.md
+- gems/well_formed-dry_types/Rakefile
+- gems/well_formed-dry_types/lib/well_formed-dry_types.rb
+- gems/well_formed-dry_types/lib/well_formed/dry_types.rb
+- gems/well_formed-dry_types/lib/well_formed/dry_types/version.rb
+- gems/well_formed-dry_types/spec/spec_helper.rb
+- gems/well_formed-dry_types/spec/well_formed/dry_types_spec.rb
+- gems/well_formed-dry_types/well_formed-dry_types.gemspec
+- gems/well_formed-paper_trail/.rspec
+- gems/well_formed-paper_trail/Gemfile
+- gems/well_formed-paper_trail/README.md
+- gems/well_formed-paper_trail/Rakefile
+- gems/well_formed-paper_trail/lib/well_formed-paper_trail.rb
+- gems/well_formed-paper_trail/lib/well_formed/paper_trail.rb
+- gems/well_formed-paper_trail/lib/well_formed/paper_trail/version.rb
+- gems/well_formed-paper_trail/spec/spec_helper.rb
+- gems/well_formed-paper_trail/spec/well_formed/paper_trail_spec.rb
+- gems/well_formed-paper_trail/well_formed-paper_trail.gemspec
 - gems/well_formed-pundit/.rspec
 - gems/well_formed-pundit/Gemfile
 - gems/well_formed-pundit/README.md
@@ -59,6 +79,7 @@ files:
 - lib/well_formed/attribute_assignment.rb
 - lib/well_formed/collections.rb
 - lib/well_formed/errors.rb
+- lib/well_formed/extensions.rb
 - lib/well_formed/initializer.rb
 - lib/well_formed/nested_attributes.rb
 - lib/well_formed/nested_form.rb