well_formed 0.1.0

data/Rakefile

@@ -0,0 +1,36 @@
+# 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)
+
+EXTENSION_GEMS = Dir.glob(File.join(__dir__, "gems", "*")).select { |d| File.directory?(d) }
+
+namespace :gems do
+  task install: :environment do
+    EXTENSION_GEMS.each do |gem_dir|
+      sh "bundle install", chdir: gem_dir
+    end
+  end
+
+  task spec: :environment do
+    EXTENSION_GEMS.each do |gem_dir|
+      sh "bundle exec rake spec", chdir: gem_dir
+    end
+  end
+
+  task rubocop: :environment do
+    EXTENSION_GEMS.each do |gem_dir|
+      sh "bundle exec rake rubocop", chdir: gem_dir
+    end
+  end
+
+  task all: %i[spec rubocop]
+end
+
+task default: %i[spec rubocop]

data/Steepfile

@@ -0,0 +1,17 @@
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+  check "lib"
+  configure_code_diagnostics(D::Ruby.lenient)
+end
+
+# target :test do
+#   unreferenced!                     # Skip type checking the `lib` code when types in `test` target is changed
+#   signature "sig/test"              # Put RBS files for tests under `sig/test`
+#   check "test"                      # Type check Ruby scripts under `test`
+#
+#   configure_code_diagnostics(D::Ruby.lenient)      # Weak type checking for test code
+#
+#   # library "pathname"              # Standard libraries
+# end

data/gems/well_formed-pundit/.rspec

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

data/gems/well_formed-pundit/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+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/gems/well_formed-pundit/README.md

@@ -0,0 +1,73 @@
+# well_formed-pundit
+
+[Pundit](https://github.com/varvet/pundit) authorization integration for [WellFormed](https://github.com/bmorrall/well_formed) form objects.
+
+Adds `policy`, `authorize!`, and `policy_scope` helpers directly to any WellFormed form, using the form's built-in `resource` and `user` references.
+
+## Installation
+
+```bash
+bundle add well_formed-pundit
+```
+
+## Usage
+
+Require the gem in your application:
+
+```ruby
+require "well_formed-pundit"
+```
+
+`WellFormed::Pundit` is automatically included into all WellFormed forms — no `include` required.
+
+### `authorize!`
+
+Raise `Pundit::NotAuthorizedError` if the user is not permitted to perform an action on the resource:
+
+```ruby
+class CreateArticleForm < WellFormed::ResourceForm
+  resource_alias :article
+
+  attribute :title, :string
+  attribute :body,  :string
+
+  validates :title, presence: true
+
+  def perform
+    authorize!(:create?)                  # authorizes resource
+    authorize!(parent_record, :update?)   # authorizes a different record
+    # proceed with save ...
+  end
+end
+```
+
+### `policy`
+
+Access the resolved Pundit policy instance directly. Defaults to the form's `resource`, but accepts an optional record argument:
+
+```ruby
+form.policy           # => ArticlePolicy for resource
+form.policy.create?   # => true / false
+form.policy(other)    # => policy resolved for a different record
+```
+
+### `policy_scope`
+
+Resolve a scoped collection for the current user:
+
+```ruby
+articles = form.policy_scope(Article.all)
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `policy(record = resource)` | Returns the Pundit policy instance for `record` and `user` |
+| `authorize!(query)` | Raises `Pundit::NotAuthorizedError` unless the user is authorized for `resource` |
+| `authorize!(record, query)` | Raises `Pundit::NotAuthorizedError` unless the user is authorized for `record` |
+| `policy_scope(collection)` | Returns the policy scope resolved for `user` |
+
+## License
+
+MIT

data/gems/well_formed-pundit/Rakefile

@@ -0,0 +1,12 @@
+# 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)
+
+task default: %i[spec rubocop]

data/gems/well_formed-pundit/lib/well_formed/pundit/version.rb

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

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module WellFormed
+  module Pundit
+    # Returns the Pundit policy instance for the given record (defaults to resource).
+    def policy(record = resource)
+      ::Pundit::PolicyFinder.new(record).policy!.new(user, record)
+    end
+
+    # Returns the scoped collection for the current user.
+    def policy_scope(collection)
+      ::Pundit::PolicyFinder.new(collection).scope!.new(user, collection).resolve
+    end
+
+    # Raises Pundit::NotAuthorizedError if the user is not authorized for the given query.
+    # Optionally pass an explicit record as the first argument; defaults to resource.
+    def authorize!(record_or_query, query = nil)
+      if query.nil?
+        ::Pundit.authorize(user, resource, record_or_query)
+      else
+        ::Pundit.authorize(user, record_or_query, query)
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "well_formed-pundit"
+
+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-pundit/spec/well_formed/pundit_integration_spec.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# Integration spec: exercises real Pundit policy resolution (no doubles)
+
+Article = Struct.new(:id)
+
+class ArticlePolicy
+  attr_reader :user, :record
+
+  def initialize(user, record)
+    @user = user
+    @record = record
+  end
+
+  def create? = user[:admin]
+  def update? = user[:admin]
+
+  class Scope
+    attr_reader :user, :scope
+
+    def initialize(user, scope)
+      @user = user
+      @scope = scope
+    end
+
+    def resolve
+      user[:admin] ? :all : :restricted
+    end
+  end
+end
+
+RSpec.describe WellFormed::Pundit, :integration do
+  let(:article) { Article.new(1) }
+  let(:admin) { {admin: true} }
+  let(:guest) { {admin: false} }
+
+  let(:form_class) do
+    stub_const("UpdateArticleForm", Class.new(WellFormed::ResourceForm) do
+      attribute :title, :string
+    end)
+  end
+
+  describe "#policy" do
+    subject(:form) { form_class.new(article, admin) }
+
+    it "returns the ArticlePolicy instance" do
+      expect(form.policy).to be_a(ArticlePolicy)
+    end
+
+    it "passes user and record to the policy" do
+      expect(form.policy.user).to eq(admin)
+      expect(form.policy.record).to eq(article)
+    end
+
+    it "uses an explicit record when provided" do
+      other_article = Article.new(2)
+      expect(form.policy(other_article).record).to eq(other_article)
+    end
+  end
+
+  describe "#authorize!" do
+    context "when the user is authorized" do
+      subject(:form) { form_class.new(article, admin) }
+
+      it "does not raise" do
+        expect { form.authorize!(:update?) }.not_to raise_error
+      end
+
+      it "accepts an explicit record as the first argument" do
+        other_article = Article.new(2)
+        expect { form.authorize!(other_article, :update?) }.not_to raise_error
+      end
+    end
+
+    context "when the user is not authorized" do
+      subject(:form) { form_class.new(article, guest) }
+
+      it "raises Pundit::NotAuthorizedError" do
+        expect { form.authorize!(:update?) }.to raise_error(::Pundit::NotAuthorizedError)
+      end
+    end
+  end
+
+  describe "#policy_scope" do
+    context "when the user is an admin" do
+      subject(:form) { form_class.new(article, admin) }
+
+      it "returns :all" do
+        expect(form.policy_scope(Article)).to eq(:all)
+      end
+    end
+
+    context "when the user is a guest" do
+      subject(:form) { form_class.new(article, guest) }
+
+      it "returns :restricted" do
+        expect(form.policy_scope(Article)).to eq(:restricted)
+      end
+    end
+  end
+end

data/gems/well_formed-pundit/spec/well_formed/pundit_spec.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+RSpec.describe WellFormed::Pundit do
+  it "has a version number" do
+    expect(WellFormed::Pundit::VERSION).not_to be_nil
+  end
+
+  let(:resource) { double("resource") }
+  let(:user) { double("user") }
+
+  let(:form_class) do
+    stub_const("TestForm", Class.new(WellFormed::ResourceForm) do
+      attribute :title, :string
+    end)
+  end
+
+  subject(:form) { form_class.new(resource, user) }
+
+  describe "auto-include via WithUser" do
+    it "is included automatically when WithUser is prepended" do
+      expect(form_class.ancestors).to include(WellFormed::Pundit)
+    end
+  end
+
+  describe "#policy" do
+    it "returns the Pundit policy for the resource and user" do
+      policy_instance = double("policy_instance")
+      policy_class = double("policy_class", new: policy_instance)
+      policy_finder = double("policy_finder", policy!: policy_class)
+
+      allow(::Pundit::PolicyFinder).to receive(:new).with(resource).and_return(policy_finder)
+
+      expect(form.policy).to eq(policy_instance)
+    end
+
+    it "accepts an explicit record argument" do
+      other_record = double("other_record")
+      policy_instance = double("policy_instance")
+      policy_class = double("policy_class", new: policy_instance)
+      policy_finder = double("policy_finder", policy!: policy_class)
+
+      allow(::Pundit::PolicyFinder).to receive(:new).with(other_record).and_return(policy_finder)
+
+      expect(form.policy(other_record)).to eq(policy_instance)
+    end
+  end
+
+  describe "#authorize!" do
+    it "delegates to Pundit.authorize with resource" do
+      allow(::Pundit).to receive(:authorize).with(user, resource, :create?).and_return(true)
+      expect { form.authorize!(:create?) }.not_to raise_error
+    end
+
+    it "raises Pundit::NotAuthorizedError when not authorized" do
+      allow(::Pundit).to receive(:authorize).with(user, resource, :create?)
+        .and_raise(::Pundit::NotAuthorizedError)
+      expect { form.authorize!(:create?) }.to raise_error(::Pundit::NotAuthorizedError)
+    end
+
+    it "accepts an explicit record as the first argument" do
+      other_record = double("other_record")
+      allow(::Pundit).to receive(:authorize).with(user, other_record, :update?).and_return(true)
+      expect { form.authorize!(other_record, :update?) }.not_to raise_error
+    end
+  end
+
+  describe "#policy_scope" do
+    it "resolves the scoped collection for the user" do
+      collection = double("collection")
+      resolved = double("resolved")
+      scope_instance = double("scope_instance", resolve: resolved)
+      scope_class = double("scope_class", new: scope_instance)
+      scope_finder = double("scope_finder", scope!: scope_class)
+
+      allow(::Pundit::PolicyFinder).to receive(:new).with(collection).and_return(scope_finder)
+
+      expect(form.policy_scope(collection)).to eq(resolved)
+    end
+  end
+end

data/gems/well_formed-pundit/well_formed-pundit.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "lib/well_formed/pundit/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "well_formed-pundit"
+  spec.version = WellFormed::Pundit::VERSION
+  spec.authors = ["Ben Morrall"]
+  spec.email = ["bemo56@hotmail.com"]
+
+  spec.summary = "Pundit authorization 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 "pundit", ">= 2.0"
+end

data/lib/generators/resource_form_generator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/named_base"
+
+class ResourceFormGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("templates", __dir__)
+
+  def create_form_file
+    template "form.rb.tt", File.join("app/forms", class_path, "#{base_name}_form.rb")
+  end
+
+  private
+
+  def form_class_name
+    [*class_path.map(&:camelize), "#{base_name.camelize}Form"].join("::")
+  end
+
+  def base_name
+    file_name.delete_suffix("_form")
+  end
+
+  def resource_alias_name
+    base_name
+  end
+end

data/lib/generators/templates/form.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class <%= form_class_name %> < WellFormed::ResourceForm
+  # resource_alias :<%= resource_alias_name %>
+
+  # attribute :title, :string
+
+  # merge_model_errors
+
+  # validates :title, presence: true
+
+  # save_within_transaction
+
+  # before_save :set_defaults
+  # after_save  :notify
+  # after_save_commit :notify_async
+
+  # private
+
+  # def set_defaults
+  # end
+
+  # def notify
+  # end
+
+  # def notify_async
+  # end
+end

data/lib/well_formed/action_form.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module WellFormed
+  class ActionForm < SimpleAction
+    prepend WithUser
+  end
+end

data/lib/well_formed/attribute_assignment.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module WellFormed
+  module AttributeAssignment
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def unmatched_attributes(policy)
+        raise ArgumentError, "policy must be :ignore, :warn, or :raise" unless %i[ignore warn raise].include?(policy)
+
+        @unmatched_attributes_policy = policy
+      end
+
+      def unmatched_attributes_policy
+        @unmatched_attributes_policy || :ignore
+      end
+    end
+
+    def assign_attributes_to(resource)
+      matched = attributes.select { |attr, _| resource.respond_to?("#{attr}=") }
+      unmatched_keys = attributes.keys - matched.keys
+
+      if unmatched_keys.any?
+        case self.class.unmatched_attributes_policy
+        when :warn
+          warn "#{self.class} has attributes with no setter on resource: #{unmatched_keys.join(", ")}"
+        when :raise
+          raise UnmatchedAttributesError,
+            "#{self.class} has attributes with no setter on resource: #{unmatched_keys.join(", ")}"
+        end
+      end
+
+      if resource.respond_to?(:assign_attributes)
+        resource.assign_attributes(matched)
+      else
+        matched.each { |attr, value| resource.public_send(:"#{attr}=", value) }
+      end
+    end
+  end
+end

data/lib/well_formed/collections.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module WellFormed
+  module Collections
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Declares a scoped collection for a form attribute, with optional inclusion validation
+      # and optional code-to-id resolution.
+      #
+      # Generates a +collection_for_<name>+ instance method that returns an ActiveRecord relation.
+      # The block is evaluated in the context of the form instance, so +user+, +resource+, and
+      # any other instance methods are available.
+      #
+      # @param name [Symbol] the attribute name (e.g. :user_id)
+      # @param validate [false, true, Symbol] when truthy, adds an inclusion validator.
+      #   - +true+   — validates that the attribute value exists in the collection matched by +:id+
+      #   - Symbol   — validates matched by the given field (e.g. <tt>validate: :code</tt>)
+      # @param resolves_to [false, true, Symbol] when truthy, the attribute accepts the +validate+
+      #   field value as external input (e.g. a code string) and resolves it to the +resolves_to+
+      #   field value (e.g. integer id) via an +after_validation+ callback. Also overrides
+      #   +resource_defaults+ to reverse-populate the attribute with the +validate+ field value
+      #   for edit forms. Requires +validate:+ to be a Symbol.
+      #   - +true+   — resolves to +:id+
+      #   - Symbol   — resolves to the given field (e.g. <tt>resolves_to: :uuid</tt>)
+      # @yieldreturn [ActiveRecord::Relation] the scoped collection
+      #
+      # Example (basic):
+      #   class CreatePostForm < WellFormed::ResourceForm
+      #     attribute :user_id, :integer
+      #
+      #     collection_for :user_id, validate: true do
+      #       User.all
+      #     end
+      #   end
+      #
+      # Example (code-to-id resolution):
+      #   class CreatePostForm < WellFormed::ResourceForm
+      #     attribute :user_id  # must not be typed :integer — accepts code strings
+      #
+      #     collection_for :user_id, validate: :code, resolves_to: :id do
+      #       User.all
+      #     end
+      #   end
+      def collection_for(name, validate: false, resolves_to: false, &block)
+        raise ArgumentError, "collection_for :#{name} requires a block" unless block
+
+        define_method(:"collection_for_#{name}", &block)
+
+        if resolves_to
+          unless validate.is_a?(Symbol)
+            raise ArgumentError,
+              "collection_for :#{name} requires validate: <Symbol> when resolves_to: is set"
+          end
+
+          match_field = validate
+          resolve_field = (resolves_to == true) ? :id : resolves_to
+          collection_method = :"collection_for_#{name}"
+
+          # Define a single validate method that both validates the input field
+          # value and, on success, transforms it to the resolve_field value.
+          # Uses :validate callbacks (not :validation) which are reliably set up
+          # by ActiveModel::Validations in all contexts.
+          resolve_method = :"_resolve_#{name}_to_#{resolve_field}"
+
+          define_method(resolve_method) do
+            val = public_send(name)
+            return if val.blank?
+
+            record = public_send(collection_method).find_by(match_field => val)
+            if record.nil?
+              errors.add(name, :inclusion)
+            else
+              public_send(:"#{name}=", record.public_send(resolve_field))
+            end
+          end
+
+          validate resolve_method
+
+          resolve_attr = name.to_s
+
+          prepend(Module.new do
+            define_method(:resource_defaults) do
+              defaults = super()
+              stored = resource&.public_send(resolve_attr)
+              return defaults if stored.blank?
+
+              code_value = public_send(collection_method)
+                .find_by(resolve_field => stored)
+                &.public_send(match_field)
+              defaults.merge(resolve_attr => code_value)
+            end
+          end)
+
+          return
+        end
+
+        return unless validate
+
+        match_field = (validate == true) ? :id : validate
+        collection_method = :"collection_for_#{name}"
+
+        validates name, inclusion: {
+          in: ->(record) {
+            record.public_send(collection_method).where(match_field => record.public_send(name)).pluck(match_field)
+          },
+          allow_blank: true
+        }
+      end
+    end
+  end
+end

data/lib/well_formed/errors.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module WellFormed
+  class Error < StandardError; end
+  class UnmatchedAttributesError < Error; end
+
+  class RecordInvalid < Error
+    attr_reader :record
+
+    def initialize(record)
+      @record = record
+      messages = record.errors.full_messages
+      super(messages.empty? ? "Record invalid" : "Validation failed: #{messages.join(", ")}")
+    end
+  end
+end