pundit 2.3.2 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa554bffd828649aeac4e79a802070d4e68948beacbc9c991fddab7141a965c9
-  data.tar.gz: edf9be8366e5dfcb541eff929e99a04c2bfb23b800214bc39d68c790b32d7365
+  metadata.gz: 1cc7a931867875af2c1a7cd5c4225da689b33e101f76bb7a471afb967323e615
+  data.tar.gz: 8ca35ba01f65b52b1b8bbb2061858bdc61cd0034b01818b07dbbba4b7ddd3a69
 SHA512:
-  metadata.gz: 555ccc09f0cc62c3e1da52a7eafb2c3e4805a303c884da39c2ed1c8fc13583727d3e060381ed761f5dd06fdcc71cc3f98c4c991e64db8ac3ff5ff5a460f64aac
-  data.tar.gz: be290f6d6253367e0911525969fc8bb8972db670626bd9803ccd6e7fc1a1504afd1c921a5aac506ee9cfe559a9863bfb469dca3a656909b7ffa1d74aa4c6ea36
+  metadata.gz: 0f495747f61c744c04dffa7811d3a86fc818812807a971591d71542d798d5a7aa4438333534082e755bbead592b4b1b5465e23030e535b03420c643e088bcaf1
+  data.tar.gz: 951ec8a8c02c081bc6b412bb0b5d1d6ffcc33543fa71f66fef9c4f4a6f391ea53a057e20b94bdef5faf4c8f2ef0deffd09357c9580ef6a739575c94a70d9d950

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug report
+about: Create a bug report to report a problem
+title: ''
+labels: problem
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps or runnable code to reproduce the problem.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Additional context**
+Add any other context about the problem here.

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: Feature request
+about: Suggest an idea
+title: ''
+labels: ['feature request']
+assignees: ''
+---
+
+**Please consider**
+- Could this feature break backwards-compatibility?
+- Could this feature benefit the many who use Pundit?
+- Could this feature be useful in _most_ projects that use Pundit?
+- Would this feature require Rails?
+- Am I open to creating a Pull Request with the necessary changes?
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of how you'd like to approach solving the problem.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context. Ex. if you've solved this problem in your own projects already, how that worked, and why the feature should be moved and maintained in Pundit instead.

data/.github/PULL_REQUEST_TEMPLATE/gem_release_template.md

@@ -1,8 +1,8 @@
 ## To do
 
-- [ ] Commit changes:
+- [ ] Make changes:
   - [ ] Bump `Pundit::VERSION` in `lib/pundit/version.rb`.
   - [ ] Update `CHANGELOG.md`.
-- [ ] Run `rake release`.
-- [ ] Open pull request 🚀
-- [ ] Make an announcement in [Pundit discussions](https://github.com/varvet/pundit/discussions/categories/announcements).
+- [ ] Open pull request 🚀 and merge it.
+- [ ] Run [push gem](https://github.com/varvet/pundit/actions/workflows/push_gem.yml) GitHub Action.
+- [ ] Make an announcement in [Pundit discussions](https://github.com/varvet/pundit/discussions/categories/announcements)

data/.github/workflows/main.yml

@@ -42,20 +42,25 @@ jobs:
             allow-failure: true
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
         rubygems: latest
         ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: true
+        bundler-cache: ${{ !startsWith(matrix.ruby-version, 'jruby') }}
+    - name: Bundler install (JRuby workaround)
+      if: ${{ startsWith(matrix.ruby-version, 'jruby') }}
+      run: |
+        gem install psych
+        bundle install
     - name: Run tests
       run: bundle exec rspec
 
   test:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
@@ -81,7 +86,7 @@ jobs:
   rubocop:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/.github/workflows/push_gem.yml

@@ -18,16 +18,16 @@ jobs:
     steps:
       # Set up
       - name: Harden Runner
-        uses: step-security/harden-runner@a4aa98b93cab29d9b1101a6143fb8bce00e2eac4 # v2.7.1
+        uses: step-security/harden-runner@5c7944e73c4c2a096b17a9cb74d65b6c2bbafbde # v2.9.1
         with:
           egress-policy: audit
 
-      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Set up Ruby
-        uses: ruby/setup-ruby@cacc9f1c0b3f4eb8a16a6bb0ed10897b43b9de49 # v1.176.0
+        uses: ruby/setup-ruby@a6e6f86333f0a2523ece813039b8b4be04560854 # v1.190.0
         with:
           bundler-cache: true
           ruby-version: ruby
 
       # Release
-      - uses: rubygems/release-gem@612653d273a73bdae1df8453e090060bb4db5f31 # v1
+      - uses: rubygems/release-gem@612653d273a73bdae1df8453e090060bb4db5f31 # v1+ unreleased

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 2.4.0 (2024-08-26)
+
+## Changed
+
+- Improve the `NotAuthorizedError` message to include the policy class.
+  Furthermore, in the case where the record passed is a class instead of an instance, the class name is given. (#812)
+
+## Added
+
+- Add customizable permit matcher description (#806)
+- Add support for filter_run_when_matching :focus with permissions helper. (#820)
+
 ## 2.3.2 (2024-05-08)
 
 - Refactor: First pass of Pundit::Context (#797)

data/CODE_OF_CONDUCT.md

@@ -25,4 +25,4 @@ maintainers.
 
 This Code of Conduct is adapted from the [Contributor
 Covenant](http:contributor-covenant.org), version 1.0.0, available at
-[http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)
+[https://contributor-covenant.org/version/1/0/0/](https://contributor-covenant.org/version/1/0/0/)

data/CONTRIBUTING.md

@@ -28,3 +28,4 @@ Pundit version, OS version and any stack traces you have are very valuable.
 - **Send coherent history**. Make sure each individual commit in your pull
   request is meaningful. If you had to make multiple intermediate commits while
   developing, please squash them before sending them to us.
+- **Update the CHANGELOG.** Don't forget to add your new changes to the CHANGELOG.

data/README.md

@@ -2,8 +2,8 @@
 
 [![Main](https://github.com/varvet/pundit/actions/workflows/main.yml/badge.svg)](https://github.com/varvet/pundit/actions/workflows/main.yml)
 [![Code Climate](https://api.codeclimate.com/v1/badges/a940030f96c9fb43046a/maintainability)](https://codeclimate.com/github/varvet/pundit/maintainability)
-[![Inline docs](http://inch-ci.org/github/varvet/pundit.svg?branch=main)](http://inch-ci.org/github/varvet/pundit)
-[![Gem Version](https://badge.fury.io/rb/pundit.svg)](http://badge.fury.io/rb/pundit)
+[![Inline docs](https://inch-ci.org/github/varvet/pundit.svg?branch=main)](https://inch-ci.org/github/varvet/pundit)
+[![Gem Version](https://badge.fury.io/rb/pundit.svg)](https://badge.fury.io/rb/pundit)
 
 Pundit provides a set of helpers which guide you in leveraging regular Ruby
 classes and object oriented design patterns to build a straightforward, robust, and
@@ -11,7 +11,7 @@ scalable authorization system.
 
 ## Links:
 
-- [API documentation for the most recent version](http://www.rubydoc.info/gems/pundit)
+- [API documentation for the most recent version](https://www.rubydoc.info/gems/pundit)
 - [Source Code](https://github.com/varvet/pundit)
 - [Contributing](https://github.com/varvet/pundit/blob/main/CONTRIBUTING.md)
 - [Code of Conduct](https://github.com/varvet/pundit/blob/main/CODE_OF_CONDUCT.md)
@@ -116,7 +116,7 @@ and the given record. It then infers from the action name, that it should call
 
 ``` ruby
 unless PostPolicy.new(current_user, @post).update?
-  raise Pundit::NotAuthorizedError, "not allowed to update? this #{@post.inspect}"
+  raise Pundit::NotAuthorizedError, "not allowed to PostPolicy#update? this Post"
 end
 ```
 
@@ -360,8 +360,15 @@ authorize individual instances.
 ``` ruby
 class ApplicationController < ActionController::Base
   include Pundit::Authorization
-  after_action :verify_authorized, except: :index
-  after_action :verify_policy_scoped, only: :index
+  after_action :verify_pundit_authorization
+
+  def verify_pundit_authorization
+    if action_name == "index"
+      verify_policy_scoped
+    else
+      verify_authorized
+    end
+  end
 end
 ```
 
@@ -489,7 +496,7 @@ end
 ## Rescuing a denied Authorization in Rails
 
 Pundit raises a `Pundit::NotAuthorizedError` you can
-[rescue_from](http://guides.rubyonrails.org/action_controller_overview.html#rescue-from)
+[rescue_from](https://guides.rubyonrails.org/action_controller_overview.html#rescue-from)
 in your `ApplicationController`. You can customize the `user_not_authorized`
 method in every controller.
 
@@ -503,7 +510,7 @@ class ApplicationController < ActionController::Base
 
   def user_not_authorized
     flash[:alert] = "You are not authorized to perform this action."
-    redirect_back(fallback_location: root_path)
+    redirect_back_or_to(root_path)
   end
 end
 ```
@@ -532,7 +539,7 @@ class ApplicationController < ActionController::Base
    policy_name = exception.policy.class.to_s.underscore
 
    flash[:error] = t "#{policy_name}.#{exception.query}", scope: "pundit", default: :default
-   redirect_back(fallback_location: root_path)
+   redirect_back_or_to(root_path)
  end
 end
 ```
@@ -754,6 +761,10 @@ end
 
 ### Policy Specs
 
+> [!TIP]
+> An alternative approach to Pundit policy specs is scoping them to a user context as outlined in this
+[excellent post](https://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/) and implemented in the third party [pundit-matchers](https://github.com/punditcommunity/pundit-matchers) gem.
+
 Pundit includes a mini-DSL for writing expressive tests for your policies in RSpec.
 Require `pundit/rspec` in your `spec_helper.rb`:
 
@@ -783,8 +794,40 @@ describe PostPolicy do
 end
 ```
 
-An alternative approach to Pundit policy specs is scoping them to a user context as outlined in this
-[excellent post](http://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/) and implemented in the third party [pundit-matchers](https://github.com/punditcommunity/pundit-matchers) gem.
+### Custom matcher description
+
+By default rspec includes an inspected `user` and `record` in the matcher description, which might become overly verbose:
+
+```
+PostPolicy
+  update? and show?
+    is expected to permit #<User:0x0000000104aefd80> and #<Post:0x0000000104aef8d0 @user=#<User:0x0000000104aefd80>>
+```
+
+You can override the default description with a static string, or a block:
+
+```ruby
+# static alternative: Pundit::RSpec::Matchers.description = "permit the user"
+Pundit::RSpec::Matchers.description = ->(user, record) do
+  "permit user with role #{user.role} to access record with ID #{record.id}"
+end
+```
+
+Which would make for a less chatty output:
+
+```
+PostPolicy
+  update? and show?
+    is expected to permit user with role admin to access record with ID 130
+```
+
+### Focus Support
+
+If your RSpec config has `filter_run_when_matching :focus`, you may tag the `permissions` helper like so:
+
+```
+permissions :show?, :focus do
+```
 
 ### Scope Specs
 
@@ -803,15 +846,15 @@ inherit_gem:
 # External Resources
 
 - [RailsApps Example Application: Pundit and Devise](https://github.com/RailsApps/rails-devise-pundit)
-- [Migrating to Pundit from CanCan](http://blog.carbonfive.com/2013/10/21/migrating-to-pundit-from-cancan/)
-- [Testing Pundit Policies with RSpec](http://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/)
+- [Migrating to Pundit from CanCan](https://blog.carbonfive.com/2013/10/21/migrating-to-pundit-from-cancan/)
+- [Testing Pundit Policies with RSpec](https://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/)
 - [Testing Pundit with Minitest](https://github.com/varvet/pundit/issues/204#issuecomment-60166450)
 - [Using Pundit outside of a Rails controller](https://github.com/varvet/pundit/pull/136)
-- [Straightforward Rails Authorization with Pundit](http://www.sitepoint.com/straightforward-rails-authorization-with-pundit/)
+- [Straightforward Rails Authorization with Pundit](https://www.sitepoint.com/straightforward-rails-authorization-with-pundit/)
 
 ## Other implementations
 
-- [Flask-Pundit](https://github.com/anurag90x/flask-pundit) (Python) is a [Flask](http://flask.pocoo.org/) extension "heavily inspired by" Pundit
+- [Flask-Pundit](https://github.com/anurag90x/flask-pundit) (Python) is a [Flask](https://flask.pocoo.org/) extension "heavily inspired by" Pundit
 
 # License
 

data/lib/pundit/rspec.rb

@@ -5,6 +5,16 @@ module Pundit
     module Matchers
       extend ::RSpec::Matchers::DSL
 
+      class << self
+        attr_writer :description
+
+        def description(user, record)
+          return @description.call(user, record) if defined?(@description) && @description.respond_to?(:call)
+
+          @description
+        end
+      end
+
       # rubocop:disable Metrics/BlockLength
       matcher :permit do |user, record|
         match_proc = lambda do |policy|
@@ -33,6 +43,10 @@ module Pundit
           "#{record} but #{@violating_permissions.to_sentence} #{was_were} granted"
         end
 
+        description do
+          Pundit::RSpec::Matchers.description(user, record) || super()
+        end
+
         if respond_to?(:match_when_negated)
           match(&match_proc)
           match_when_negated(&match_when_negated_proc)
@@ -55,7 +69,15 @@ module Pundit
 
     module DSL
       def permissions(*list, &block)
-        describe(list.to_sentence, permissions: list, caller: caller) { instance_eval(&block) }
+        metadata = { permissions: list, caller: caller }
+
+        if list.last == :focus
+          list.pop
+          metadata[:focus] = true
+        end
+
+        description = list.to_sentence
+        describe(description, metadata) { instance_eval(&block) }
       end
     end
 

data/lib/pundit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pundit
-  VERSION = "2.3.2"
+  VERSION = "2.4.0"
 end

data/lib/pundit.rb

@@ -36,7 +36,10 @@ module Pundit
         @record = options[:record]
         @policy = options[:policy]
 
-        message = options.fetch(:message) { "not allowed to #{query} this #{record.class}" }
+        message = options.fetch(:message) do
+          record_name = record.is_a?(Class) ? record.to_s : "this #{record.class}"
+          "not allowed to #{policy.class}##{query} #{record_name}"
+        end
       end
 
       super(message)

data/spec/authorization_spec.rb

@@ -169,7 +169,7 @@ describe Pundit::Authorization do
       expect(controller.policy_scope(Post)).to eq :published
     end
 
-    it "allows policy scope class to be overriden" do
+    it "allows policy scope class to be overridden" do
       expect(controller.policy_scope(Post, policy_scope_class: PublicationPolicy::Scope)).to eq :published
     end
 

data/spec/dsl_spec.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Pundit RSpec DSL" do
+  let(:fake_rspec) do
+    double = class_double(RSpec::ExampleGroups)
+    double.extend(::Pundit::RSpec::DSL)
+    double
+  end
+  let(:block) { proc { "block content" } }
+
+  it "calls describe with the correct metadata and without :focus" do
+    expected_metadata = { permissions: %i[item1 item2], caller: instance_of(Array) }
+    expect(fake_rspec).to receive(:describe).with("item1 and item2", match(expected_metadata)) do |&block|
+      expect(block.call).to eq("block content")
+    end
+
+    fake_rspec.permissions(:item1, :item2, &block)
+  end
+
+  it "calls describe with the correct metadata and with :focus" do
+    expected_metadata = { permissions: %i[item1 item2], caller: instance_of(Array), focus: true }
+    expect(fake_rspec).to receive(:describe).with("item1 and item2", match(expected_metadata)) do |&block|
+      expect(block.call).to eq("block content")
+    end
+
+    fake_rspec.permissions(:item1, :item2, :focus, &block)
+  end
+end

data/spec/policies/post_policy_spec.rb

@@ -18,5 +18,32 @@ RSpec.describe PostPolicy do
         should permit(user, other_post)
       end.to raise_error(RSpec::Expectations::ExpectationNotMetError)
     end
+
+    it "uses the default description if not overridden" do
+      expect(permit(user, own_post).description).to eq("permit #{user.inspect} and #{own_post.inspect}")
+    end
+
+    context "when the matcher description is overridden" do
+      after do
+        Pundit::RSpec::Matchers.description = nil
+      end
+
+      it "sets a custom matcher description with a Proc" do
+        allow(user).to receive(:role).and_return("default_role")
+        allow(own_post).to receive(:id).and_return(1)
+
+        Pundit::RSpec::Matchers.description = lambda { |user, record|
+          "permit user with role #{user.role} to access record with ID #{record.id}"
+        }
+
+        description = permit(user, own_post).description
+        expect(description).to eq("permit user with role default_role to access record with ID 1")
+      end
+
+      it "sets a custom matcher description with a string" do
+        Pundit::RSpec::Matchers.description = "permit user"
+        expect(permit(user, own_post).description).to eq("permit user")
+      end
+    end
   end
 end

data/spec/pundit_spec.rb

@@ -57,11 +57,11 @@ RSpec.describe Pundit do
       expect { Pundit.authorize(user, article_tag, :destroy?) }.to raise_error(Pundit::NotAuthorizedError)
     end
 
-    it "raises an error with a query and action" do
+    it "raises an error with the policy, query and record" do
       # rubocop:disable Style/MultilineBlockChain
       expect do
         Pundit.authorize(user, post, :destroy?)
-      end.to raise_error(Pundit::NotAuthorizedError, "not allowed to destroy? this Post") do |error|
+      end.to raise_error(Pundit::NotAuthorizedError, "not allowed to PostPolicy#destroy? this Post") do |error|
         expect(error.query).to eq :destroy?
         expect(error.record).to eq post
         expect(error.policy).to have_attributes(
@@ -73,11 +73,12 @@ RSpec.describe Pundit do
       # rubocop:enable Style/MultilineBlockChain
     end
 
-    it "raises an error with a the record, query and action when the record is namespaced" do
+    it "raises an error with the policy, query and record when the record is namespaced" do
       # rubocop:disable Style/MultilineBlockChain
       expect do
         Pundit.authorize(user, [:project, :admin, comment], :destroy?)
-      end.to raise_error(Pundit::NotAuthorizedError, "not allowed to destroy? this Comment") do |error|
+      end.to raise_error(Pundit::NotAuthorizedError,
+                         "not allowed to Project::Admin::CommentPolicy#destroy? this Comment") do |error|
         expect(error.query).to eq :destroy?
         expect(error.record).to eq comment
         expect(error.policy).to have_attributes(
@@ -89,6 +90,22 @@ RSpec.describe Pundit do
       # rubocop:enable Style/MultilineBlockChain
     end
 
+    it "raises an error with the policy, query and the class name when a Class is given" do
+      # rubocop:disable Style/MultilineBlockChain
+      expect do
+        Pundit.authorize(user, Post, :destroy?)
+      end.to raise_error(Pundit::NotAuthorizedError, "not allowed to PostPolicy#destroy? Post") do |error|
+        expect(error.query).to eq :destroy?
+        expect(error.record).to eq Post
+        expect(error.policy).to have_attributes(
+          user: user,
+          record: Post
+        )
+        expect(error.policy).to be_a(PostPolicy)
+      end
+      # rubocop:enable Style/MultilineBlockChain
+    end
+
     it "raises an error with a invalid policy constructor" do
       expect do
         Pundit.authorize(user, wiki, :update?)

data/spec/spec_helper.rb

@@ -313,7 +313,7 @@ end
 class ThreadPolicy < BasePolicy
   class Scope < BaseScope
     def resolve
-      # deliberate wrong useage of the method
+      # deliberate wrong usage of the method
       scope.all(:unvalid, :parameters)
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pundit
 version: !ruby/object:Gem::Version
-  version: 2.3.2
+  version: 2.4.0
 platform: ruby
 authors:
 - Jonas Nicklas
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-05-08 00:00:00.000000000 Z
+date: 2024-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -173,8 +173,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/ISSUE_TEMPLATE/bug_report.md"
+- ".github/ISSUE_TEMPLATE/feature_request.md"
 - ".github/PULL_REQUEST_TEMPLATE/gem_release_template.md"
-- ".github/PULL_REQUEST_TEMPLATE/pull_request_template.md"
+- ".github/pull_request_template.md"
 - ".github/workflows/main.yml"
 - ".github/workflows/push_gem.yml"
 - ".gitignore"
@@ -209,6 +211,7 @@ files:
 - lib/pundit/version.rb
 - pundit.gemspec
 - spec/authorization_spec.rb
+- spec/dsl_spec.rb
 - spec/generators_spec.rb
 - spec/policies/post_policy_spec.rb
 - spec/policy_finder_spec.rb
@@ -234,12 +237,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.5.11
 signing_key: 
 specification_version: 4
 summary: OO authorization for Rails
 test_files:
 - spec/authorization_spec.rb
+- spec/dsl_spec.rb
 - spec/generators_spec.rb
 - spec/policies/post_policy_spec.rb
 - spec/policy_finder_spec.rb