pundit 2.4.0 → 2.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cc7a931867875af2c1a7cd5c4225da689b33e101f76bb7a471afb967323e615
-  data.tar.gz: 8ca35ba01f65b52b1b8bbb2061858bdc61cd0034b01818b07dbbba4b7ddd3a69
+  metadata.gz: 5c6f7c834aabbea0d1c74b4101d67a936f0c062db2c5a67dcb45c824d0a1f80e
+  data.tar.gz: 651d652baa3a1f511e794b80f4e514b5e2bb74f75abeaa184dff48dae63e27bf
 SHA512:
-  metadata.gz: 0f495747f61c744c04dffa7811d3a86fc818812807a971591d71542d798d5a7aa4438333534082e755bbead592b4b1b5465e23030e535b03420c643e088bcaf1
-  data.tar.gz: 951ec8a8c02c081bc6b412bb0b5d1d6ffcc33543fa71f66fef9c4f4a6f391ea53a057e20b94bdef5faf4c8f2ef0deffd09357c9580ef6a739575c94a70d9d950
+  metadata.gz: e4081cc21e4827985808334e5753a6b6f812743308cc251f8e4923b0b3a73c41b64bb6da64da57919ac62672537e3d464b187f0d28811a0aaab9c17ea9354ec5
+  data.tar.gz: a7868288d12d4f63cc95b5d18f54bfdafbcf586c7f415a713713f1f520140c2f7c353572cdab770baf16f5525ec4fc369679fd5e640233360b743f34d66580d9

data/CHANGELOG.md

@@ -2,43 +2,67 @@
 
 ## Unreleased
 
+## 2.5.1 (2025-09-12)
+
+### Fixed
+- Requiring only `pundit/rspec` no longer raises an error in Active Support [#857](https://github.com/varvet/pundit/issues/857)
+
+## 2.5.0 (2025-03-03)
+
+### Added
+
+- Add `Pundit::Authorization#pundit_reset!` hook to reset the policy and policy scope cache. [#830](https://github.com/varvet/pundit/issues/830)
+- Add links to gemspec. [#845](https://github.com/varvet/pundit/issues/845)
+- Register policies directories for Rails 8 code statistics [#833](https://github.com/varvet/pundit/issues/833)
+- Added an example for how to use pundit with Rails 8 authentication generator [#850](https://github.com/varvet/pundit/issues/850)
+
+### Changed
+
+- Deprecated `Pundit::SUFFIX`, moved it to `Pundit::PolicyFinder::SUFFIX` [#835](https://github.com/varvet/pundit/issues/835)
+- Explicitly require less of `active_support` [#837](https://github.com/varvet/pundit/issues/837)
+- Using `permit` matcher without a surrouding `permissions` block now raises a useful error. [#836](https://github.com/varvet/pundit/issues/836)
+
+### Fixed
+
+- Using a hash as custom cache in `Pundit.authorize` now works as documented. [#838](https://github.com/varvet/pundit/issues/838)
+
 ## 2.4.0 (2024-08-26)
 
-## Changed
+### 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)
+  Furthermore, in the case where the record passed is a class instead of an instance, the class name is given. [#812](https://github.com/varvet/pundit/issues/812)
 
-## Added
+### Added
 
-- Add customizable permit matcher description (#806)
-- Add support for filter_run_when_matching :focus with permissions helper. (#820)
+- Add customizable permit matcher description [#806](https://github.com/varvet/pundit/issues/806)
+- Add support for filter_run_when_matching :focus with permissions helper. [#820](https://github.com/varvet/pundit/issues/820)
 
 ## 2.3.2 (2024-05-08)
 
-- Refactor: First pass of Pundit::Context (#797)
+- Refactor: First pass of Pundit::Context [#797](https://github.com/varvet/pundit/issues/797)
 
-## Changed
+### Changed
 
-- Update `ApplicationPolicy` generator to qualify the `Scope` class name (#792)
-- Policy generator uses `NoMethodError` to indicate `#resolve` is not implemented (#776)
+- Update `ApplicationPolicy` generator to qualify the `Scope` class name [#792](https://github.com/varvet/pundit/issues/792)
+- Policy generator uses `NoMethodError` to indicate `#resolve` is not implemented [#776](https://github.com/varvet/pundit/issues/776)
 
 ## Deprecated
 
-- Dropped support for Ruby 3.0 (#796)
+- Dropped support for Ruby 3.0 [#796](https://github.com/varvet/pundit/issues/796)
 
 ## 2.3.1 (2023-07-17)
 
 ### Fixed
 
-- Use `Kernel.warn` instead of `ActiveSupport::Deprecation.warn` for deprecations (#764)
-- Policy generator now works on Ruby 3.2 (#754)
+- Use `Kernel.warn` instead of `ActiveSupport::Deprecation.warn` for deprecations [#764](https://github.com/varvet/pundit/issues/764)
+- Policy generator now works on Ruby 3.2 [#754](https://github.com/varvet/pundit/issues/754)
 
 ## 2.3.0 (2022-12-19)
 
 ### Added
 
-- add support for rubocop-rspec syntax extensions (#745)
+- add support for rubocop-rspec syntax extensions [#745](https://github.com/varvet/pundit/issues/745)
 
 ## 2.2.0 (2022-02-11)
 
@@ -52,41 +76,41 @@
 
 ### Deprecated
 
-- Deprecate `include Pundit` in favor of `include Pundit::Authorization` (#621)
+- Deprecate `include Pundit` in favor of `include Pundit::Authorization` [#621](https://github.com/varvet/pundit/issues/621)
 
 ## 2.1.1 (2021-08-13)
 
 Friday 13th-release!
 
-Careful! The bugfix below (#626) could break existing code. If you rely on the
+Careful! The bugfix below [#626](https://github.com/varvet/pundit/issues/626) could break existing code. If you rely on the
 return value for `authorize` and namespaced policies you might need to do some
 changes.
 
 ### Fixed
 
 - `.authorize` and `#authorize` return the instance, even for namespaced
-  policies (#626)
+  policies [#626](https://github.com/varvet/pundit/issues/626)
 
 ### Changed
 
-- Generate application scope with `protected` attr_readers. (#616)
+- Generate application scope with `protected` attr_readers. [#616](https://github.com/varvet/pundit/issues/616)
 
 ### Removed
 
-- Dropped support for Ruby end-of-life versions: 2.1 and 2.2. (#604)
-- Dropped support for Ruby end-of-life versions: 2.3 (#633)
-- Dropped support for Ruby end-of-life versions: 2.4, 2.5 and JRuby 9.1 (#676)
-- Dropped support for RSpec 2 (#615)
+- Dropped support for Ruby end-of-life versions: 2.1 and 2.2. [#604](https://github.com/varvet/pundit/issues/604)
+- Dropped support for Ruby end-of-life versions: 2.3 [#633](https://github.com/varvet/pundit/issues/633)
+- Dropped support for Ruby end-of-life versions: 2.4, 2.5 and JRuby 9.1 [#676](https://github.com/varvet/pundit/issues/676)
+- Dropped support for RSpec 2 [#615](https://github.com/varvet/pundit/issues/615)
 
 ## 2.1.0 (2019-08-14)
 
 ### Fixed
 
-- Avoid name clashes with the Error class. (#590)
+- Avoid name clashes with the Error class. [#590](https://github.com/varvet/pundit/issues/590)
 
 ### Changed
 
-- Return a safer default NotAuthorizedError message. (#583)
+- Return a safer default NotAuthorizedError message. [#583](https://github.com/varvet/pundit/issues/583)
 
 ## 2.0.1 (2019-01-18)
 
@@ -96,8 +120,8 @@ None
 
 ### Other changes
 
-- Improve exception handling for `#policy_scope` and `#policy_scope!`. (#550)
-- Add `:policy` metadata to RSpec template. (#566)
+- Improve exception handling for `#policy_scope` and `#policy_scope!`. [#550](https://github.com/varvet/pundit/issues/550)
+- Add `:policy` metadata to RSpec template. [#566](https://github.com/varvet/pundit/issues/566)
 
 ## 2.0.0 (2018-07-21)
 
@@ -107,20 +131,20 @@ No changes since beta1
 
 ### Breaking changes
 
-- Only pass last element of "namespace array" to policy and scope. (#529)
-- Raise `InvalidConstructorError` if a policy or policy scope with an invalid constructor is called. (#462)
-- Return passed object from `#authorize` method to make chaining possible. (#385)
+- Only pass last element of "namespace array" to policy and scope. [#529](https://github.com/varvet/pundit/issues/529)
+- Raise `InvalidConstructorError` if a policy or policy scope with an invalid constructor is called. [#462](https://github.com/varvet/pundit/issues/462)
+- Return passed object from `#authorize` method to make chaining possible. [#385](https://github.com/varvet/pundit/issues/385)
 
 ### Other changes
 
-- Add `policy_class` option to `authorize` to be able to override the policy. (#441)
-- Add `policy_scope_class` option to `authorize` to be able to override the policy scope. (#441)
-- Fix `param_key` issue when passed an array. (#529)
-- Allow specification of a `NilClassPolicy`. (#525)
-- Make sure `policy_class` override is called when passed an array. (#475)
+- Add `policy_class` option to `authorize` to be able to override the policy. [#441](https://github.com/varvet/pundit/issues/441)
+- Add `policy_scope_class` option to `authorize` to be able to override the policy scope. [#441](https://github.com/varvet/pundit/issues/441)
+- Fix `param_key` issue when passed an array. [#529](https://github.com/varvet/pundit/issues/529)
+- Allow specification of a `NilClassPolicy`. [#525](https://github.com/varvet/pundit/issues/525)
+- Make sure `policy_class` override is called when passed an array. [#475](https://github.com/varvet/pundit/issues/475)
 
-- Use `action_name` instead of `params[:action]`. (#419)
-- Add `pundit_params_for` method to make it easy to customize params fetching. (#502)
+- Use `action_name` instead of `params[:action]`. [#419](https://github.com/varvet/pundit/issues/419)
+- Add `pundit_params_for` method to make it easy to customize params fetching. [#502](https://github.com/varvet/pundit/issues/502)
 
 ## 1.1.0 (2016-01-14)
 
@@ -152,16 +176,16 @@ No changes since beta1
 
 ## 0.3.0 (2014-08-22)
 
-- Extend the default `ApplicationPolicy` with an `ApplicationPolicy::Scope` (#120)
-- Fix RSpec 3 deprecation warnings for built-in matchers (#162)
-- Generate blank policy spec/test files for Rspec/MiniTest/Test::Unit in Rails (#138)
+- Extend the default `ApplicationPolicy` with an `ApplicationPolicy::Scope` [#120](https://github.com/varvet/pundit/issues/120)
+- Fix RSpec 3 deprecation warnings for built-in matchers [#162](https://github.com/varvet/pundit/issues/162)
+- Generate blank policy spec/test files for Rspec/MiniTest/Test::Unit in Rails [#138](https://github.com/varvet/pundit/issues/138)
 
 ## 0.2.3 (2014-04-06)
 
-- Customizable error messages: `#query`, `#record` and `#policy` methods on `Pundit::NotAuthorizedError` (#114)
-- Raise a different `Pundit::AuthorizationNotPerformedError` when `authorize` call is expected in controller action but missing (#109)
-- Update Rspec matchers for Rspec 3 (#124)
+- Customizable error messages: `#query`, `#record` and `#policy` methods on `Pundit::NotAuthorizedError` [#114](https://github.com/varvet/pundit/issues/114)
+- Raise a different `Pundit::AuthorizationNotPerformedError` when `authorize` call is expected in controller action but missing [#109](https://github.com/varvet/pundit/issues/109)
+- Update Rspec matchers for Rspec 3 [#124](https://github.com/varvet/pundit/issues/124)
 
 ## 0.2.2 (2014-02-07)
 
-- Customize the user to be passed into policies: `pundit_user` (#42)
+- Customize the user to be passed into policies: `pundit_user` [#42](https://github.com/varvet/pundit/issues/42)

data/README.md

@@ -1,7 +1,7 @@
 # Pundit
 
 [![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)
+[![Maintainability](https://qlty.sh/gh/varvet/projects/pundit/maintainability.svg)](https://qlty.sh/gh/varvet/projects/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)
 
@@ -583,6 +583,36 @@ def pundit_user
 end
 ```
 
+For instance, Rails 8 includes a built-in [authentication generator](https://github.com/rails/rails/tree/8-0-stable/railties/lib/rails/generators/rails/authentication). If you choose to use it, the currently logged-in user is accessed via `Current.user` instead of `current_user`.
+
+To ensure compatibility with Pundit, define a `pundit_user` method in `application_controller.rb` (or another suitable location) as follows:
+
+```ruby
+def pundit_user
+  Current.user
+end
+```
+
+### Handling User Switching in Pundit
+
+When switching users in your application, it's important to reset the Pundit user context to ensure that authorization policies are applied correctly for the new user. Pundit caches the user context, so failing to reset it could result in incorrect permissions being applied.
+
+To handle user switching, you can use the following pattern in your controller:
+
+```ruby
+class ApplicationController
+  include Pundit::Authorization
+
+  def switch_user_to(user)
+    terminate_session if authenticated?
+    start_new_session_for user
+    pundit_reset!
+  end
+end
+```
+
+Make sure to invoke `pundit_reset!` whenever changing the user. This ensures the cached authorization context is reset, preventing any incorrect permissions from being applied.
+
 ## Policy Namespacing
 In some cases it might be helpful to have multiple policies that serve different contexts for a
 resource. A prime example of this is the case where User policies differ from Admin policies. To

data/lib/generators/pundit/install/install_generator.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 module Pundit
+  # @private
   module Generators
+    # @private
     class InstallGenerator < ::Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
       def copy_application_policy
-        template "application_policy.rb", "app/policies/application_policy.rb"
+        template "application_policy.rb.tt", "app/policies/application_policy.rb"
       end
     end
   end

data/lib/generators/pundit/policy/policy_generator.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 module Pundit
+  # @private
   module Generators
+    # @private
     class PolicyGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
       def create_policy
-        template "policy.rb", File.join("app/policies", class_path, "#{file_name}_policy.rb")
+        template "policy.rb.tt", File.join("app/policies", class_path, "#{file_name}_policy.rb")
       end
 
       hook_for :test_framework

data/lib/generators/rspec/policy_generator.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
+# @private
 module Rspec
+  # @private
   module Generators
+    # @private
     class PolicyGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
       def create_policy_spec
-        template "policy_spec.rb", File.join("spec/policies", class_path, "#{file_name}_policy_spec.rb")
+        template "policy_spec.rb.tt", File.join("spec/policies", class_path, "#{file_name}_policy_spec.rb")
       end
     end
   end

data/lib/generators/test_unit/policy_generator.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
+# @private
 module TestUnit
+  # @private
   module Generators
+    # @private
     class PolicyGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
       def create_policy_test
-        template "policy_test.rb", File.join("test/policies", class_path, "#{file_name}_policy_test.rb")
+        template "policy_test.rb.tt", File.join("test/policies", class_path, "#{file_name}_policy_test.rb")
       end
     end
   end

data/lib/pundit/authorization.rb

@@ -1,6 +1,15 @@
 # frozen_string_literal: true
 
 module Pundit
+  # Pundit DSL to include in your controllers to provide authorization helpers.
+  #
+  # @example
+  #   class ApplicationController < ActionController::Base
+  #     include Pundit::Authorization
+  #   end
+  # @see #pundit
+  # @api public
+  # @since v2.2.0
   module Authorization
     extend ActiveSupport::Concern
 
@@ -15,7 +24,14 @@ module Pundit
 
     protected
 
-    # @return [Pundit::Context] a new instance of {Pundit::Context} with the current user
+    # An instance of {Pundit::Context} initialized with the current user.
+    #
+    # @note this method is memoized and will return the same instance during the request.
+    # @api public
+    # @return [Pundit::Context]
+    # @see #pundit_user
+    # @see #policies
+    # @since v2.3.2
     def pundit
       @pundit ||= Pundit::Context.new(
         user: pundit_user,
@@ -23,40 +39,40 @@ module Pundit
       )
     end
 
-    # @return [Boolean] whether authorization has been performed, i.e. whether
-    #                   one {#authorize} or {#skip_authorization} has been called
-    def pundit_policy_authorized?
-      !!@_pundit_policy_authorized
-    end
-
-    # @return [Boolean] whether policy scoping has been performed, i.e. whether
-    #                   one {#policy_scope} or {#skip_policy_scope} has been called
-    def pundit_policy_scoped?
-      !!@_pundit_policy_scoped
-    end
-
-    # Raises an error if authorization has not been performed, usually used as an
-    # `after_action` filter to prevent programmer error in forgetting to call
-    # {#authorize} or {#skip_authorization}.
+    # Hook method which allows customizing which user is passed to policies and
+    # scopes initialized by {#authorize}, {#policy} and {#policy_scope}.
     #
-    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
-    # @raise [AuthorizationNotPerformedError] if authorization has not been performed
-    # @return [void]
-    def verify_authorized
-      raise AuthorizationNotPerformedError, self.class unless pundit_policy_authorized?
+    # @note Make sure to call `pundit_reset!` if this changes during a request.
+    # @see https://github.com/varvet/pundit#customize-pundit-user
+    # @see #pundit
+    # @see #pundit_reset!
+    # @return [Object] the user object to be used with pundit
+    # @since v0.2.2
+    def pundit_user
+      current_user
     end
 
-    # Raises an error if policy scoping has not been performed, usually used as an
-    # `after_action` filter to prevent programmer error in forgetting to call
-    # {#policy_scope} or {#skip_policy_scope} in index actions.
+    # Clears the cached Pundit authorization data.
+    #
+    # This method should be called when the pundit_user is changed,
+    # such as during user switching, to ensure that stale authorization
+    # data is not used. Pundit caches authorization policies and scopes
+    # for the pundit_user, so calling this method will reset those
+    # caches and ensure that the next authorization checks are performed
+    # with the correct context for the new pundit_user.
     #
-    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
-    # @raise [AuthorizationNotPerformedError] if policy scoping has not been performed
     # @return [void]
-    def verify_policy_scoped
-      raise PolicyScopingNotPerformedError, self.class unless pundit_policy_scoped?
+    # @since v2.5.0
+    def pundit_reset!
+      @pundit = nil
+      @_pundit_policies = nil
+      @_pundit_policy_scopes = nil
+      @_pundit_policy_authorized = nil
+      @_pundit_policy_scoped = nil
     end
 
+    # @!group Policies
+
     # Retrieves the policy for the given record, initializing it with the record
     # and current user and finally throwing an error if the user is not
     # authorized to perform the given action.
@@ -66,7 +82,10 @@ module Pundit
     #   If omitted then this defaults to the Rails controller action name.
     # @param policy_class [Class] the policy class we want to force use of
     # @raise [NotAuthorizedError] if the given query method returned false
-    # @return [Object] Always returns the passed object record
+    # @return [record] Always returns the passed object record
+    # @see Pundit::Context#authorize
+    # @see #verify_authorized
+    # @since v0.1.0
     def authorize(record, query = nil, policy_class: nil)
       query ||= "#{action_name}?"
 
@@ -79,49 +98,153 @@ module Pundit
     #
     # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
     # @return [void]
+    # @see #verify_authorized
+    # @since v1.0.0
     def skip_authorization
       @_pundit_policy_authorized = :skipped
     end
 
-    # Allow this action not to perform policy scoping.
+    # @return [Boolean] wether or not authorization has been performed
+    # @see #authorize
+    # @see #skip_authorization
+    # @since v1.0.0
+    def pundit_policy_authorized?
+      !!@_pundit_policy_authorized
+    end
+
+    # Raises an error if authorization has not been performed.
+    #
+    # Usually used as an `after_action` filter to prevent programmer error in
+    # forgetting to call {#authorize} or {#skip_authorization}.
     #
     # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @raise [AuthorizationNotPerformedError] if authorization has not been performed
     # @return [void]
-    def skip_policy_scope
-      @_pundit_policy_scoped = :skipped
+    # @see #authorize
+    # @see #skip_authorization
+    # @since v0.1.0
+    def verify_authorized
+      raise AuthorizationNotPerformedError, self.class unless pundit_policy_authorized?
     end
 
-    # Retrieves the policy scope for the given record.
+    # rubocop:disable Naming/MemoizedInstanceVariableName
+
+    # Cache of policies. You should not rely on this method.
     #
-    # @see https://github.com/varvet/pundit#scopes
-    # @param scope [Object] the object we're retrieving the policy scope for
-    # @param policy_scope_class [Class] the policy scope class we want to force use of
-    # @return [Scope{#resolve}, nil] instance of scope class which can resolve to a scope
-    def policy_scope(scope, policy_scope_class: nil)
-      @_pundit_policy_scoped = true
-      policy_scope_class ? policy_scope_class.new(pundit_user, scope).resolve : pundit_policy_scope(scope)
+    # @api private
+    # @since v1.0.0
+    def policies
+      @_pundit_policies ||= {}
     end
 
+    # rubocop:enable Naming/MemoizedInstanceVariableName
+
+    # @!endgroup
+
     # Retrieves the policy for the given record.
     #
     # @see https://github.com/varvet/pundit#policies
     # @param record [Object] the object we're retrieving the policy for
     # @return [Object] instance of policy class with query methods
+    # @since v0.1.0
     def policy(record)
       pundit.policy!(record)
     end
 
-    # Retrieves a set of permitted attributes from the policy by instantiating
-    # the policy class for the given record and calling `permitted_attributes` on
-    # it, or `permitted_attributes_for_{action}` if `action` is defined. It then infers
-    # what key the record should have in the params hash and retrieves the
-    # permitted attributes from the params hash under that key.
+    # @!group Policy Scopes
+
+    # Retrieves the policy scope for the given record.
+    #
+    # @see https://github.com/varvet/pundit#scopes
+    # @param scope [Object] the object we're retrieving the policy scope for
+    # @param policy_scope_class [#resolve] the policy scope class we want to force use of
+    # @return [#resolve, nil] instance of scope class which can resolve to a scope
+    # @since v0.1.0
+    def policy_scope(scope, policy_scope_class: nil)
+      @_pundit_policy_scoped = true
+      policy_scope_class ? policy_scope_class.new(pundit_user, scope).resolve : pundit_policy_scope(scope)
+    end
+
+    # Allow this action not to perform policy scoping.
+    #
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @return [void]
+    # @see #verify_policy_scoped
+    # @since v1.0.0
+    def skip_policy_scope
+      @_pundit_policy_scoped = :skipped
+    end
+
+    # @return [Boolean] wether or not policy scoping has been performed
+    # @see #policy_scope
+    # @see #skip_policy_scope
+    # @since v1.0.0
+    def pundit_policy_scoped?
+      !!@_pundit_policy_scoped
+    end
+
+    # Raises an error if policy scoping has not been performed.
+    #
+    # Usually used as an `after_action` filter to prevent programmer error in
+    # forgetting to call {#policy_scope} or {#skip_policy_scope} in index
+    # actions.
+    #
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @raise [AuthorizationNotPerformedError] if policy scoping has not been performed
+    # @return [void]
+    # @see #policy_scope
+    # @see #skip_policy_scope
+    # @since v0.2.1
+    def verify_policy_scoped
+      raise PolicyScopingNotPerformedError, self.class unless pundit_policy_scoped?
+    end
+
+    # rubocop:disable Naming/MemoizedInstanceVariableName
+
+    # Cache of policy scope. You should not rely on this method.
+    #
+    # @api private
+    # @since v1.0.0
+    def policy_scopes
+      @_pundit_policy_scopes ||= {}
+    end
+
+    # rubocop:enable Naming/MemoizedInstanceVariableName
+
+    # This was added to allow calling `policy_scope!` without flipping the
+    # `pundit_policy_scoped?` flag.
+    #
+    # It's used internally by `policy_scope`, as well as from the views
+    # when they call `policy_scope`. It works because views get their helper
+    # from {Pundit::Helper}.
+    #
+    # @note This also memoizes the instance with `scope` as the key.
+    # @see Pundit::Helper#policy_scope
+    # @api private
+    # @since v1.0.0
+    def pundit_policy_scope(scope)
+      policy_scopes[scope] ||= pundit.policy_scope!(scope)
+    end
+    private :pundit_policy_scope
+
+    # @!endgroup
+
+    # @!group Strong Parameters
+
+    # Retrieves a set of permitted attributes from the policy.
+    #
+    # Done by instantiating the policy class for the given record and calling
+    # `permitted_attributes` on it, or `permitted_attributes_for_{action}` if
+    # `action` is defined. It then infers what key the record should have in the
+    # params hash and retrieves the permitted attributes from the params hash
+    # under that key.
     #
     # @see https://github.com/varvet/pundit#strong-parameters
     # @param record [Object] the object we're retrieving permitted attributes for
     # @param action [Symbol, String] the name of the action being performed on the record (e.g. `:update`).
     #   If omitted then this defaults to the Rails controller action name.
     # @return [Hash{String => Object}] the permitted attributes
+    # @since v1.0.0
     def permitted_attributes(record, action = action_name)
       policy = policy(record)
       method_name = if policy.respond_to?("permitted_attributes_for_#{action}")
@@ -136,41 +259,11 @@ module Pundit
     #
     # @param record [Object] the object we're retrieving params for
     # @return [ActionController::Parameters] the params
+    # @since v2.0.0
     def pundit_params_for(record)
       params.require(PolicyFinder.new(record).param_key)
     end
 
-    # Cache of policies. You should not rely on this method.
-    #
-    # @api private
-    # rubocop:disable Naming/MemoizedInstanceVariableName
-    def policies
-      @_pundit_policies ||= {}
-    end
-    # rubocop:enable Naming/MemoizedInstanceVariableName
-
-    # Cache of policy scope. You should not rely on this method.
-    #
-    # @api private
-    # rubocop:disable Naming/MemoizedInstanceVariableName
-    def policy_scopes
-      @_pundit_policy_scopes ||= {}
-    end
-    # rubocop:enable Naming/MemoizedInstanceVariableName
-
-    # Hook method which allows customizing which user is passed to policies and
-    # scopes initialized by {#authorize}, {#policy} and {#policy_scope}.
-    #
-    # @see https://github.com/varvet/pundit#customize-pundit-user
-    # @return [Object] the user object to be used with pundit
-    def pundit_user
-      current_user
-    end
-
-    private
-
-    def pundit_policy_scope(scope)
-      policy_scopes[scope] ||= pundit.policy_scope!(scope)
-    end
+    # @!endgroup
   end
 end