pundit 2.4.0 → 2.5.0

data/lib/pundit/rspec.rb

@@ -1,13 +1,29 @@
 # frozen_string_literal: true
 
+# Array#to_sentence
+require "active_support/core_ext/array/conversions"
+
 module Pundit
+  # Namespace for Pundit's RSpec integration.
   module RSpec
+    # Namespace for Pundit's RSpec matchers.
     module Matchers
       extend ::RSpec::Matchers::DSL
 
+      # @!method description=(description)
       class << self
+        # Used to build a suitable description for the Pundit `permit` matcher.
+        # @api public
+        # @param value [String, Proc]
+        # @example
+        #   Pundit::RSpec::Matchers.description = ->(user, record) do
+        #     "permit user with role #{user.role} to access record with ID #{record.id}"
+        #   end
         attr_writer :description
 
+        # Used to retrieve a suitable description for the Pundit `permit` matcher.
+        # @api private
+        # @private
         def description(user, record)
           return @description.call(user, record) if defined?(@description) && @description.respond_to?(:call)
 
@@ -32,15 +48,21 @@ module Pundit
         end
 
         failure_message_proc = lambda do |policy|
-          was_were = @violating_permissions.count > 1 ? "were" : "was"
           "Expected #{policy} to grant #{permissions.to_sentence} on " \
-          "#{record} but #{@violating_permissions.to_sentence} #{was_were} not granted"
+          "#{record} but #{@violating_permissions.to_sentence} #{was_or_were} not granted"
         end
 
         failure_message_when_negated_proc = lambda do |policy|
-          was_were = @violating_permissions.count > 1 ? "were" : "was"
           "Expected #{policy} not to grant #{permissions.to_sentence} on " \
-          "#{record} but #{@violating_permissions.to_sentence} #{was_were} granted"
+          "#{record} but #{@violating_permissions.to_sentence} #{was_or_were} granted"
+        end
+
+        def was_or_were
+          if @violating_permissions.count > 1
+            "were"
+          else
+            "was"
+          end
         end
 
         description do
@@ -53,21 +75,57 @@ module Pundit
           failure_message(&failure_message_proc)
           failure_message_when_negated(&failure_message_when_negated_proc)
         else
+          # :nocov:
+          # Compatibility with RSpec < 3.0, released 2014-06-01.
           match_for_should(&match_proc)
           match_for_should_not(&match_when_negated_proc)
           failure_message_for_should(&failure_message_proc)
           failure_message_for_should_not(&failure_message_when_negated_proc)
+          # :nocov:
+        end
+
+        if ::RSpec.respond_to?(:current_example)
+          def current_example
+            ::RSpec.current_example
+          end
+        else
+          # :nocov:
+          # Compatibility with RSpec < 3.0, released 2014-06-01.
+          def current_example
+            example
+          end
+          # :nocov:
         end
 
         def permissions
-          current_example = ::RSpec.respond_to?(:current_example) ? ::RSpec.current_example : example
-          current_example.metadata[:permissions]
+          current_example.metadata.fetch(:permissions) do
+            raise KeyError, <<~ERROR.strip
+              No permissions in example metadata, did you forget to wrap with `permissions :show?, ...`?
+            ERROR
+          end
         end
       end
       # rubocop:enable Metrics/BlockLength
     end
 
+    # Mixed in to all policy example groups to provide a DSL.
     module DSL
+      # @example
+      #   describe PostPolicy do
+      #     permissions :show?, :update? do
+      #       it { is_expected.to permit(user, own_post) }
+      #     end
+      #   end
+      #
+      # @example focused example group
+      #   describe PostPolicy do
+      #     permissions :show?, :update?, :focus do
+      #       it { is_expected.to permit(user, own_post) }
+      #     end
+      #   end
+      #
+      # @param list [Symbol, Array<Symbol>] a permission to describe
+      # @return [void]
       def permissions(*list, &block)
         metadata = { permissions: list, caller: caller }
 
@@ -81,6 +139,9 @@ module Pundit
       end
     end
 
+    # Mixed in to all policy example groups.
+    #
+    # @private not useful
     module PolicyExampleGroup
       include Pundit::RSpec::Matchers
 

data/lib/pundit/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Pundit
-  VERSION = "2.4.0"
+  # The current version of Pundit.
+  VERSION = "2.5.0"
 end

data/lib/pundit.rb

@@ -1,33 +1,53 @@
 # frozen_string_literal: true
 
+require "active_support"
+
 require "pundit/version"
 require "pundit/policy_finder"
-require "active_support/concern"
-require "active_support/core_ext/string/inflections"
-require "active_support/core_ext/object/blank"
-require "active_support/core_ext/module/introspection"
-require "active_support/dependencies/autoload"
 require "pundit/authorization"
 require "pundit/context"
+require "pundit/cache_store"
 require "pundit/cache_store/null_store"
 require "pundit/cache_store/legacy_store"
+require "pundit/railtie" if defined?(Rails)
 
 # @api private
 # To avoid name clashes with common Error naming when mixing in Pundit,
 # keep it here with compact class style definition.
 class Pundit::Error < StandardError; end # rubocop:disable Style/ClassAndModuleChildren
 
+# Hello? Yes, this is Pundit.
+#
 # @api public
 module Pundit
-  SUFFIX = "Policy"
+  # @api private
+  # @deprecated See {Pundit::PolicyFinder}
+  SUFFIX = Pundit::PolicyFinder::SUFFIX
 
   # @api private
+  # @private
   module Generators; end
 
   # Error that will be raised when authorization has failed
   class NotAuthorizedError < Error
-    attr_reader :query, :record, :policy
-
+    # @see #initialize
+    attr_reader :query
+    # @see #initialize
+    attr_reader :record
+    # @see #initialize
+    attr_reader :policy
+
+    # @overload initialize(message)
+    #   Create an error with a simple error message.
+    #   @param [String] message A simple error message string.
+    #
+    # @overload initialize(options)
+    #   Create an error with the specified attributes.
+    #   @param [Hash] options The error options.
+    #   @option options [String] :message Optional custom error message. Will default to a generalized message.
+    #   @option options [Symbol] :query The name of the policy method that was checked.
+    #   @option options [Object] :record The object that was being checked with the policy.
+    #   @option options [Class] :policy The class of policy that was used for the check.
     def initialize(options = {})
       if options.is_a? String
         message = options
@@ -70,10 +90,11 @@ module Pundit
   end
 
   class << self
-    # @see [Pundit::Context#authorize]
+    # @see Pundit::Context#authorize
     def authorize(user, record, query, policy_class: nil, cache: nil)
       context = if cache
-        Context.new(user: user, policy_cache: cache)
+        policy_cache = CacheStore::LegacyStore.new(cache)
+        Context.new(user: user, policy_cache: policy_cache)
       else
         Context.new(user: user)
       end
@@ -81,29 +102,33 @@ module Pundit
       context.authorize(record, query: query, policy_class: policy_class)
     end
 
-    # @see [Pundit::Context#policy_scope]
+    # @see Pundit::Context#policy_scope
     def policy_scope(user, *args, **kwargs, &block)
       Context.new(user: user).policy_scope(*args, **kwargs, &block)
     end
 
-    # @see [Pundit::Context#policy_scope!]
+    # @see Pundit::Context#policy_scope!
     def policy_scope!(user, *args, **kwargs, &block)
       Context.new(user: user).policy_scope!(*args, **kwargs, &block)
     end
 
-    # @see [Pundit::Context#policy]
+    # @see Pundit::Context#policy
     def policy(user, *args, **kwargs, &block)
       Context.new(user: user).policy(*args, **kwargs, &block)
     end
 
-    # @see [Pundit::Context#policy!]
+    # @see Pundit::Context#policy!
     def policy!(user, *args, **kwargs, &block)
       Context.new(user: user).policy!(*args, **kwargs, &block)
     end
   end
 
+  # Rails view helpers, to allow a slightly different view-specific
+  # implementation of the methods in {Pundit::Authorization}.
+  #
   # @api private
   module Helper
+    # @see Pundit::Authorization#pundit_policy_scope
     def policy_scope(scope)
       pundit_policy_scope(scope)
     end

data/pundit.gemspec

@@ -16,20 +16,16 @@ Gem::Specification.new do |gem|
 
   gem.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
   gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
-  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.metadata      = { "rubygems_mfa_required" => "true" }
+  gem.metadata      = {
+    "rubygems_mfa_required" => "true",
+    "bug_tracker_uri" => "https://github.com/varvet/pundit/issues",
+    "changelog_uri" => "https://github.com/varvet/pundit/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://github.com/varvet/pundit/blob/main/README.md",
+    "homepage_uri" => "https://github.com/varvet/pundit",
+    "source_code_uri" => "https://github.com/varvet/pundit"
+  }
 
   gem.add_dependency "activesupport", ">= 3.0.0"
-  gem.add_development_dependency "actionpack", ">= 3.0.0"
-  gem.add_development_dependency "activemodel", ">= 3.0.0"
-  gem.add_development_dependency "bundler"
-  gem.add_development_dependency "pry"
-  gem.add_development_dependency "railties", ">= 3.0.0"
-  gem.add_development_dependency "rake"
-  gem.add_development_dependency "rspec", ">= 3.0.0"
-  gem.add_development_dependency "rubocop"
-  gem.add_development_dependency "simplecov", ">= 0.17.0"
-  gem.add_development_dependency "yard"
 end

data/spec/authorization_spec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "spec_helper"
+require "action_controller/metal/strong_parameters"
 
 describe Pundit::Authorization do
   def to_params(*args, **kwargs, &block)
@@ -8,7 +9,7 @@ describe Pundit::Authorization do
   end
 
   let(:controller) { Controller.new(user, "update", to_params({})) }
-  let(:user) { double }
+  let(:user) { double("user") }
   let(:post) { Post.new(user) }
   let(:comment) { Comment.new }
   let(:article) { Article.new }
@@ -157,7 +158,7 @@ describe Pundit::Authorization do
     end
 
     it "allows policy to be injected" do
-      new_policy = OpenStruct.new
+      new_policy = double
       controller.policies[post] = new_policy
 
       expect(controller.policy(post)).to eq new_policy
@@ -182,7 +183,7 @@ describe Pundit::Authorization do
     end
 
     it "allows policy_scope to be injected" do
-      new_scope = OpenStruct.new
+      new_scope = double
       controller.policy_scopes[Post] = new_scope
 
       expect(controller.policy_scope(Post)).to eq new_scope
@@ -271,4 +272,60 @@ describe Pundit::Authorization do
       expect(Controller.new(user, action, params).permitted_attributes(post, :revise).to_h).to eq("body" => "blah")
     end
   end
+
+  describe "#pundit_reset!" do
+    it "allows authorize to react to a user change" do
+      expect(controller.authorize(post)).to be_truthy
+
+      controller.current_user = double
+      controller.pundit_reset!
+      expect { controller.authorize(post) }.to raise_error(Pundit::NotAuthorizedError)
+    end
+
+    it "allows policy to react to a user change" do
+      expect(controller.policy(DummyCurrentUser).user).to be user
+
+      new_user = double("new user")
+      controller.current_user = new_user
+      controller.pundit_reset!
+      expect(controller.policy(DummyCurrentUser).user).to be new_user
+    end
+
+    it "allows policy scope to react to a user change" do
+      expect(controller.policy_scope(DummyCurrentUser)).to be user
+
+      new_user = double("new user")
+      controller.current_user = new_user
+      controller.pundit_reset!
+      expect(controller.policy_scope(DummyCurrentUser)).to be new_user
+    end
+
+    it "resets the pundit context" do
+      expect(controller.pundit.user).to be(user)
+
+      new_user = double
+      controller.current_user = new_user
+      expect { controller.pundit_reset! }.to change { controller.pundit.user }.from(user).to(new_user)
+    end
+
+    it "clears pundit_policy_authorized? flag" do
+      expect(controller.pundit_policy_authorized?).to be false
+
+      controller.skip_authorization
+      expect(controller.pundit_policy_authorized?).to be true
+
+      controller.pundit_reset!
+      expect(controller.pundit_policy_authorized?).to be false
+    end
+
+    it "clears pundit_policy_scoped? flag" do
+      expect(controller.pundit_policy_scoped?).to be false
+
+      controller.skip_policy_scope
+      expect(controller.pundit_policy_scoped?).to be true
+
+      controller.pundit_reset!
+      expect(controller.pundit_policy_scoped?).to be false
+    end
+  end
 end

data/spec/policy_finder_spec.rb

@@ -2,13 +2,17 @@
 
 require "spec_helper"
 
-class Foo; end
 RSpec.describe Pundit::PolicyFinder do
   let(:user) { double }
   let(:post) { Post.new(user) }
   let(:comment) { CommentFourFiveSix.new }
   let(:article) { Article.new }
 
+  describe "SUFFIX" do
+    specify { expect(described_class::SUFFIX).to eq "Policy" }
+    specify { expect(Pundit::SUFFIX).to eq(described_class::SUFFIX) }
+  end
+
   describe "#scope" do
     subject { described_class.new(post) }
 

data/spec/pundit/helper_spec.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Pundit::Helper do
+  let(:user) { double }
+  let(:controller) { Controller.new(user, "update", double) }
+  let(:view) { Controller::View.new(controller) }
+
+  describe "#policy_scope" do
+    it "doesn't flip pundit_policy_scoped?" do
+      scoped = view.policy_scope(Post)
+
+      expect(scoped).to be(Post.published)
+      expect(controller).not_to be_pundit_policy_scoped
+    end
+  end
+end

data/spec/pundit_spec.rb

@@ -43,15 +43,6 @@ RSpec.describe Pundit do
       expect(Pundit.authorize(user, Post, :show?)).to eq(Post)
     end
 
-    it "can be given a different policy class" do
-      expect(Pundit.authorize(user, post, :create?, policy_class: PublicationPolicy)).to be_truthy
-    end
-
-    it "can be given a different policy class using namespaces" do
-      expect(PublicationPolicy).to receive(:new).with(user, comment).and_call_original
-      expect(Pundit.authorize(user, [:project, comment], :create?, policy_class: PublicationPolicy)).to be_truthy
-    end
-
     it "works with anonymous class policies" do
       expect(Pundit.authorize(user, article_tag, :show?)).to be_truthy
       expect { Pundit.authorize(user, article_tag, :destroy?) }.to raise_error(Pundit::NotAuthorizedError)
@@ -111,6 +102,41 @@ RSpec.describe Pundit do
         Pundit.authorize(user, wiki, :update?)
       end.to raise_error(Pundit::InvalidConstructorError, "Invalid #<WikiPolicy> constructor is called")
     end
+
+    context "when passed a policy class" do
+      it "uses the passed policy class" do
+        expect(Pundit.authorize(user, post, :create?, policy_class: PublicationPolicy)).to be_truthy
+      end
+
+      # This is documenting past behaviour.
+      it "doesn't cache the policy class" do
+        cache = {}
+
+        expect do
+          Pundit.authorize(user, post, :create?, policy_class: PublicationPolicy, cache: cache)
+          Pundit.authorize(user, post, :create?, policy_class: PublicationPolicy, cache: cache)
+        end.to change { PublicationPolicy.instances }.by(2)
+      end
+    end
+
+    context "when passed a policy class while simultaenously passing a namespace" do
+      it "uses the passed policy class" do
+        expect(PublicationPolicy).to receive(:new).with(user, comment).and_call_original
+        expect(Pundit.authorize(user, [:project, comment], :create?, policy_class: PublicationPolicy)).to be_truthy
+      end
+    end
+
+    context "when passed an explicit cache" do
+      it "uses the hash assignment interface on the cache" do
+        custom_cache = CustomCache.new
+
+        Pundit.authorize(user, post, :update?, cache: custom_cache)
+
+        expect(custom_cache.to_h).to match({
+          post => kind_of(PostPolicy)
+        })
+      end
+    end
   end
 
   describe ".policy_scope" do
@@ -154,8 +180,8 @@ RSpec.describe Pundit do
 
     it "raises an original error with a policy scope that contains error" do
       expect do
-        Pundit.policy_scope(user, Thread)
-      end.to raise_error(ArgumentError)
+        Pundit.policy_scope(user, DefaultScopeContainsError)
+      end.to raise_error(RuntimeError, "This is an arbitrary error that should bubble up")
     end
   end
 

data/spec/rspec_dsl_spec.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Pundit RSpec DSL" do
+  include Pundit::RSpec::PolicyExampleGroup
+
+  let(:fake_rspec) do
+    double = class_double(RSpec::ExampleGroups)
+    double.extend(::Pundit::RSpec::DSL)
+    double
+  end
+  let(:block) { proc { "block content" } }
+
+  let(:user) { double }
+  let(:other_user) { double }
+  let(:post) { Post.new(user) }
+  let(:policy) { PostPolicy }
+
+  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
+
+  describe "#permit" do
+    context "when not appropriately wrapped in permissions" do
+      it "raises a descriptive error" do
+        expect do
+          expect(policy).to permit(user, post)
+        end.to raise_error(KeyError, <<~MSG.strip)
+          No permissions in example metadata, did you forget to wrap with `permissions :show?, ...`?
+        MSG
+      end
+    end
+
+    permissions :edit?, :update? do
+      it "succeeds when action is permitted" do
+        expect(policy).to permit(user, post)
+      end
+
+      context "when it fails" do
+        it "fails with a descriptive error message" do
+          expect do
+            expect(policy).to permit(other_user, post)
+          end.to raise_error(RSpec::Expectations::ExpectationNotMetError, <<~MSG.strip)
+            Expected PostPolicy to grant edit? and update? on Post but edit? and update? were not granted
+          MSG
+        end
+      end
+
+      context "when negated" do
+        it "succeeds when action is not permitted" do
+          expect(policy).not_to permit(other_user, post)
+        end
+
+        context "when it fails" do
+          it "fails with a descriptive error message" do
+            expect do
+              expect(policy).not_to permit(user, post)
+            end.to raise_error(RSpec::Expectations::ExpectationNotMetError, <<~MSG.strip)
+              Expected PostPolicy not to grant edit? and update? on Post but edit? and update? were granted
+            MSG
+          end
+        end
+      end
+    end
+  end
+end

data/spec/simple_cov_check_action_formatter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "simplecov"
+require "json"
+
+class SimpleCovCheckActionFormatter
+  SourceFile = Data.define(:source_file) do
+    def covered_strength = source_file.covered_strength
+    def covered_percent = source_file.covered_percent
+
+    def to_json(*args)
+      {
+        filename: source_file.filename,
+        covered_percent: covered_percent.nan? ? 0.0 : covered_percent,
+        coverage: source_file.coverage_data,
+        covered_strength: covered_strength.nan? ? 0.0 : covered_strength,
+        covered_lines: source_file.covered_lines.count,
+        lines_of_code: source_file.lines_of_code
+      }.to_json(*args)
+    end
+  end
+
+  Result = Data.define(:result) do
+    def included?(source_file) = result.filenames.include?(source_file.filename)
+
+    def files
+      result.files.filter_map do |source_file|
+        next unless result.filenames.include? source_file.filename
+
+        SourceFile.new(source_file)
+      end
+    end
+
+    def to_json(*args) # rubocop:disable Metrics/AbcSize
+      {
+        timestamp: result.created_at.to_i,
+        command_name: result.command_name,
+        files: files,
+        metrics: {
+          covered_percent: result.covered_percent,
+          covered_strength: result.covered_strength.nan? ? 0.0 : result.covered_strength,
+          covered_lines: result.covered_lines,
+          total_lines: result.total_lines
+        }
+      }.to_json(*args)
+    end
+  end
+
+  FormatterWithOptions = Data.define(:formatter) do
+    def new = formatter
+  end
+
+  class << self
+    def with_options(...)
+      FormatterWithOptions.new(new(...))
+    end
+  end
+
+  def initialize(output_filename: "coverage.json", output_directory: SimpleCov.coverage_path)
+    @output_filename = output_filename
+    @output_directory = output_directory
+  end
+
+  attr_reader :output_filename, :output_directory
+
+  def output_filepath = File.join(output_directory, output_filename)
+
+  def format(result_data)
+    result = Result.new(result_data)
+    json = JSON.generate(result)
+    File.write(output_filepath, json)
+    puts output_message(result_data)
+    json
+  end
+
+  def output_message(result)
+    "Coverage report generated for #{result.command_name} to #{output_filepath}. #{result.covered_lines} / #{result.total_lines} LOC (#{result.covered_percent.round(2)}%) covered." # rubocop:disable Layout/LineLength
+  end
+end