Merge branch 'main' into rails-stats

.github/workflows/main.yml

@@ -2,9 +2,8 @@ name: Main
 
 on:
   push:
-    branches: [ "main" ]
+    branches: ["main"]
   pull_request:
-    branches: [ "main" ]
   workflow_dispatch:
 
 permissions:
@@ -28,85 +27,121 @@ jobs:
       fail-fast: false
       matrix:
         ruby-version:
-          - '3.1'
-          - '3.2'
-          - '3.3'
-          - 'jruby-9.3.10' # oldest supported jruby
-          - 'jruby'
+          - "3.1"
+          - "3.2"
+          - "3.3"
+          - "jruby-9.3.15"
+          - "jruby"
         include: # HEAD-versions
-          - ruby-version: 'head'
+          - ruby-version: "head"
             allow-failure: true
-          - ruby-version: 'jruby-head'
+          - ruby-version: "jruby-head"
             allow-failure: true
-          - ruby-version: 'truffleruby-head'
+          - ruby-version: "truffleruby-head"
             allow-failure: true
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        rubygems: latest
-        ruby-version: ${{ matrix.ruby-version }}
-        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
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          rubygems: latest
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rspec
 
   test:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        rubygems: latest
-        ruby-version: 'ruby'
-        bundler-cache: true
-    - name: "Download cc-test-reporter from codeclimate.com"
-      run: |
-        curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
-        chmod +x ./cc-test-reporter
-    - name: "Report to Code Climate that we will send a coverage report."
-      run: ./cc-test-reporter before-build
-    - name: Run tests
-      run: bundle exec rspec
-      env:
-        COVERAGE: 1
-    - name: Upload code coverage to Code Climate
-      run: |
-        ./cc-test-reporter after-build \
-          --coverage-input-type simplecov \
-          ./coverage/.resultset.json
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          rubygems: latest
+          ruby-version: "ruby"
+          bundler-cache: true
+      - name: "Download cc-test-reporter from codeclimate.com"
+        run: |
+          curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+          chmod +x ./cc-test-reporter
+      - name: "Report to Code Climate that we will send a coverage report."
+        run: ./cc-test-reporter before-build
+      - name: Run tests
+        run: bundle exec rspec
+        env:
+          COVERAGE: 1
+      - name: Upload coverage results
+        uses: actions/upload-artifact@v4
+        with:
+          include-hidden-files: true
+          name: coverage-results
+          path: coverage
+          retention-days: 1
+      - name: Upload code coverage to Code Climate
+        run: |
+          ./cc-test-reporter after-build \
+            --coverage-input-type simplecov \
+            ./coverage/.resultset.json
+
+  coverage-check:
+    permissions:
+      contents: read
+      checks: write
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download coverage results
+        uses: actions/download-artifact@v4
+        with:
+          name: coverage-results
+          path: coverage
+      - uses: joshmfrankel/simplecov-check-action@be89e11889202cc59efb14aab2a7091622fa9aad
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          minimum_suite_coverage: 100
+          minimum_file_coverage: 100
+          coverage_json_path: coverage/simplecov-check-action.json
 
   rubocop:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        rubygems: default
-        ruby-version: 'ruby'
-        bundler-cache: false
-    - run: bundle install
-    - name: Run RuboCop
-      run: bundle exec rubocop
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          rubygems: default
+          ruby-version: "ruby"
+          bundler-cache: false
+      - run: bundle install
+      - name: Run RuboCop
+        run: bundle exec rubocop
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          rubygems: default
+          ruby-version: "ruby"
+          bundler-cache: false
+      - run: bundle install
+      - run: rake yard
 
   required-checks:
     runs-on: ubuntu-latest
     if: ${{ always() }}
     needs:
       - test
       - matrix-test
+      - docs
       - rubocop
     steps:
       - name: failure
         if: ${{ failure() || contains(needs.*.result, 'failure') }}
         run: exit 1
       - name: success
-        run: exit 0
+        run: exit 0

.rubocop.yml

@@ -1,16 +1,20 @@
+inherit_from: .rubocop_ignore_git.yml
+
 AllCops:
   TargetRubyVersion: 3.1
-  Exclude:
-    - "lib/generators/**/templates/**/*"
-    <% `git status --ignored --porcelain`.lines.grep(/^!! /).each do |path| %>
-    - <%= path.sub(/^!! /, '').sub(/\/$/, '/**/*') %>
-    <% end %>
   SuggestExtensions: false
   NewCops: disable
 
+Gemspec/DeprecatedAttributeAssignment:
+  Enabled: true
+
+Gemspec/DevelopmentDependencies:
+  Enabled: true
+
 Metrics/BlockLength:
   Exclude:
     - "**/*_spec.rb"
+    - pundit.gemspec
 
 Metrics/MethodLength:
   Max: 40
@@ -24,7 +28,7 @@ Layout/LineLength:
   Max: 120
 
 Gemspec/RequiredRubyVersion:
- Enabled: false
+  Enabled: false
 
 Layout/ParameterAlignment:
   EnforcedStyle: with_fixed_indentation
@@ -36,13 +40,19 @@ Layout/CaseIndentation:
     - end
   IndentOneStep: true
 
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
 Layout/EndAlignment:
   EnforcedStyleAlignWith: variable
 
 Style/PercentLiteralDelimiters:
   PreferredDelimiters:
-    '%w': "[]"
-    '%W': "[]"
+    "%w": "[]"
+    "%W": "[]"
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes

.rubocop_ignore_git.yml

@@ -0,0 +1,7 @@
+# This is here so we can keep YAML syntax highlight in the main file.
+AllCops:
+  Exclude:
+    - "lib/generators/**/templates/**/*"
+    <% `git status --ignored --porcelain`.lines.grep(/^!! /).each do |path| %>
+    - <%= path.sub(/^!! /, '').sub(/\/$/, '/**/*') %>
+    <% end %>

.yardopts

@@ -1 +1 @@
---api public --hide-void-return --markup markdown
+--no-private --private --protected --hide-void-return --markup markdown --fail-on-warning

CHANGELOG.md

@@ -2,10 +2,22 @@
 
 ## Unreleased
 
-### Added
+## Added
 
+- Add `Pundit::Authorization#pundit_reset!` hook to reset the policy and policy scope cache. (#830)
+- Add links to gemspec. (#845)
 - Register policies directories for Rails 8 code statistics (#833)
 
+## Changed
+
+- Deprecated `Pundit::SUFFIX`, moved it to `Pundit::PolicyFinder::SUFFIX` (#835)
+- Explicitly require less of `active_support` (#837)
+- Using `permit` matcher without a surrouding `permissions` block now raises a useful error. (#836)
+
+### Fixed
+
+- Using a hash as custom cache in `Pundit.authorize` now works as documented. (#838)
+
 ## 2.4.0 (2024-08-26)
 
 ## Changed

Gemfile

@@ -4,5 +4,25 @@ source "https://rubygems.org"
 
 gemspec
 
-# https://github.com/ruby/psych/issues/655
-gem "psych", "!= 5.1.1", platforms: %i[jruby]
+# Rails-related - for testing purposes
+gem "actionpack", ">= 3.0.0" # Used to test strong parameters
+gem "activemodel", ">= 3.0.0" # Used to test ActiveModel::Naming
+gem "railties", ">= 3.0.0" # Used to test generators
+
+# Testing
+gem "rspec", ">= 3.0.0"
+gem "simplecov", ">= 0.17.0"
+
+# Development tools
+gem "bundler"
+gem "rake"
+gem "rubocop"
+gem "rubocop-performance"
+gem "rubocop-rspec"
+gem "yard"
+gem "zeitwerk"
+
+# Affects us on JRuby 9.3.15.
+#
+# @see https://github.com/rails/rails/issues/54260
+gem "logger"

README.md

@@ -582,6 +582,25 @@ def pundit_user
   User.find_by_other_means
 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

Rakefile

@@ -15,6 +15,7 @@ end
 
 YARD::Rake::YardocTask.new do |t|
   t.files = ["lib/**/*.rb"]
+  t.stats_options = ["--list-undoc"]
 end
 
 task default: :spec

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

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

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