consent 0.6.0 → 2.0.0

data/lib/consent/permission_migration.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Consent
+  # Permission migration helper module
+  module PermissionMigration
+    # Copy permissions from one existing permission into a new permission selecting with
+    # attrs would be overrided.
+    #
+    # I.e.:
+    #
+    #   copy_permissions(
+    #     from: { subject: :sale, action: :view },
+    #     override: { subject: :project }
+    #   )
+    #
+    # @param from [Hash] a hash with `:subject` and `:action` to select which permissions to copy
+    # @param override [Hash] hash to specify which fields/values to override
+    #
+    def copy_permissions(from:, override:)
+      raise ArgumentError, "Subject and Action are always required" if from[:subject].blank? || from[:action].blank?
+
+      ::Consent::Permission.to(**from).each do |permission|
+        ::Consent::Permission.create!(
+          permission.slice(:subject, :action, :view, :role_id).merge(override)
+        )
+      end
+    end
+
+    # Grant a permission to a collection of roles.
+    #
+    # I.e.:
+    #
+    #   grant_permission(
+    #     subject: :view_installer_pay_report,
+    #     action: ProjectTask,
+    #     role_ids: [2, 7, 140]
+    #   )
+    #
+    # @param subject [symbol] the permission's subject
+    # @param action [Class, symbol] the permission's action
+    # @param role_ids [Array<Integer>] the collection of role_ids to grant the permission to
+    # @param view [String, nil] the view level, or access level, that the permission will be
+    #   assigned at. If not specified, this will default to true ("1")
+    #
+    def grant_permission(subject:, action:, role_ids:, view: "1")
+      role_ids.each do |role_id|
+        ::Consent::Permission.create!(subject: subject,
+                                      action: action,
+                                      role_id: role_id,
+                                      view: view)
+      end
+    end
+
+    # Removes a permission from a collection of roles.
+    #
+    # I.e.:
+    #
+    #   remove_permission(
+    #     subject: :view,
+    #     action: User,
+    #     role_ids: [78, 12]
+    #   )
+    #
+    # @param subject [symbol] the permission's subject
+    # @param action [Class, symbol] the permission's action
+    # @param role_ids [Array<Integer>] the collection of role_ids to grant the permission to
+    #
+    def remove_permission(subject:, action:, role_ids:)
+      role_ids.each do |role_id|
+        permission = ::Consent::Permission.find_by(subject: subject,
+                                                   action: action,
+                                                   role_id: role_id)
+        permission.destroy!
+      end
+    end
+
+    # Batch updates permission data
+    #
+    # * CAUTION *
+    #    Updating a permission in a migration means that for some time the old permission
+    #  will be broken in production. So, you might lock out people between the permission
+    #  running and your code getting deployed/restarted in the webservers.
+    #
+    #  Example:
+    #  - Page A is only displayed to users that `can? :view, Candidate`
+    #  - If you're willing to rename the `view` action to be `view_candidates`
+    #  - Then you could go with a permission like this
+    #     update_permissions(
+    #      from: { subject: :candidate, action: :view },
+    #      to: { action: :view_candidates }
+    #     )
+    #  - And you'll have to change the permission check to be `can? :view_candidates, Candidate`
+    #  - When you merge your PR, then the migration will run first, and later on your code will
+    #    reach production.
+    #  - Between that time, the page that uses that permission will be unreachable since
+    #  `can? :view, Candidate` doesn't exists anymore in the DB.
+    #
+    # I.e.:
+    #
+    # Renames a subject affecting all grantted permissions keeping everything else
+    #
+    #   update_permissions(
+    #     from: { subject: :sale },
+    #     to: { subject: :project }
+    #   )
+    #
+    # Moves an action from a subject to another keeping the view
+    #
+    #   update_permissions(
+    #     from: { subject: :sale, action: :perform },
+    #     to: { subject: :project }
+    #   )
+    #
+    # Rename an action within a subject keeping the view
+    #
+    #   update_permissions(
+    #     from: { subject: :sale, action: :read },
+    #     to: { action: :inspect }
+    #   )
+    #
+    # Rename a view within a subject and action context
+    #
+    #   update_permissions(
+    #     from: { subject: :sale, action: :read, view: :territory },
+    #     to: { view: :department_territory }
+    #   )
+    #
+    # @param from [Hash] a hash with `:subject`, `:action`, and `:view` to match the affected permissions
+    # @param to [Hash] a hash with `:subject`, `:action`, and/or `:view` with the desired change
+    #
+    def update_permissions(from:, to:)
+      raise ArgumentError, "Subject is always required" if from[:subject].blank?
+
+      ::Consent::Permission.to(**from).find_each do |permission|
+        permission.update(to)
+      end
+    end
+  end
+end

data/lib/consent/reloader.rb

@@ -2,20 +2,21 @@
 
 module Consent
   # Rails file reloader to detect permission changes and apply them to consent
+  # @private
   class Reloader
     attr_reader :paths
+
     delegate :updated?, :execute, :execute_if_updated, to: :updater
 
-    def initialize(default_path, mechanism)
+    def initialize(default_path)
       @paths = [default_path]
-      @mechanism = mechanism
     end
 
-    private
+  private
 
     def reload!
       Consent.subjects.clear
-      Consent.load_subjects! paths, @mechanism
+      Consent.load_subjects! paths
     end
 
     def updater
@@ -24,7 +25,7 @@ module Consent
 
     def globs
       pairs = paths.map { |path| [path.to_s, %w[rb]] }
-      Hash[pairs]
+      pairs.to_h
     end
   end
 end

data/lib/consent/rspec/consent_action.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "consent"
+RSpec::Support.require_rspec_support "fuzzy_matcher"
+
+module Consent
+  module Rspec
+    # @private
+    class ConsentAction
+      def initialize(action_key)
+        @action_key = action_key
+      end
+
+      def with_views(*views)
+        @views = views
+        self
+      end
+
+      def description
+        message = "consents action #{@action_key}"
+        "#{message} with views #{@views}" if @views
+      end
+
+      def matches?(subject_key)
+        @subject_key = subject_key
+        @action = Consent.find_action(@subject_key, @action_key)
+        if @action && @views
+          RSpec::Support::FuzzyMatcher.values_match?(
+            @action.views.keys.sort,
+            @views.sort
+          )
+        else
+          !@action.nil?
+        end
+      end
+
+      def failure_message
+        failure_message_base "to"
+      end
+
+      def failure_message_when_negated
+        failure_message_base "to not"
+      end
+
+    private
+
+      def failure_message_base(failure) # rubocop:disable Metrics/MethodLength
+        message = format(
+          "expected %<skey>s (%<sclass>s) %<failure> provide action %<action>s",
+          skey: @subject_key.to_s, sclass: @subject_key.class,
+          action: @action_key, failure: failure
+        )
+
+        if @action && @views
+          format(
+            "%<message>s with views %<views>s, but actual views are %<keys>p",
+            message: message, views: @views, keys: @action.views.keys
+          )
+        else
+          message
+        end
+      end
+    end
+  end
+end

data/lib/consent/rspec/consent_view.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Consent
+  module Rspec
+    # @private
+    class ConsentView
+      def initialize(view_key, conditions)
+        @conditions = comparable_conditions(conditions) if conditions
+        @view_key = view_key
+      end
+
+      def to(*context)
+        @context = context
+        self
+      end
+
+      def description
+        message = "consents view #{@view_key}"
+        "#{message} with conditions #{@conditions}" if @conditions
+      end
+
+      def with_conditions(conditions)
+        @conditions = comparable_conditions(conditions)
+        self
+      end
+
+      def matches?(subject_key)
+        @subject_key = subject_key
+        @target = Consent.find_subjects(subject_key)
+                         .filter_map { |subject| subject.views[@view_key]&.conditions(*@context) }
+                         .map { |c| comparable_conditions(c) }
+        @target.include?(@conditions)
+      end
+
+      def failure_message
+        failure_message_base "to"
+      end
+
+      def failure_message_when_negated
+        failure_message_base "to not"
+      end
+
+    private
+
+      def comparable_conditions(conditions)
+        return conditions.to_sql if conditions.respond_to?(:to_sql)
+
+        conditions
+      end
+
+      def failure_message_base(failure) # rubocop:disable Metrics/MethodLength
+        message = format(
+          'expected %<skey>s (%<sclass>s) %<fail>s provide view %<view>s with`\
+          `%<conditions>p, but',
+          skey: @subject_key.to_s, sclass: @subject_key.class,
+          view: @view_key, conditions: @conditions, fail: failure
+        )
+
+        if @target.any?
+          format(
+            "%<message>s conditions are %<conditions>p",
+            message: message, conditions: @target
+          )
+        else
+          actual_views = Consent.find_subjects(@subject_key)
+                                .map(&:views)
+                                .map(&:keys).flatten
+          format(
+            "%<message>s available views are %<views>p",
+            message: message, views: actual_views
+          )
+        end
+      end
+    end
+  end
+end

data/lib/consent/rspec.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
-require 'consent'
+require "consent"
+
+require_relative "rspec/consent_action"
+require_relative "rspec/consent_view"
 
 module Consent
   # RSpec helpers for consent. Given permissions are loaded,
@@ -20,7 +23,11 @@ module Consent
   #   let(:user) { double(department_id: 15) }
   #
   #   it do
-  #     is_expected.to consent_view(:department, department_id: 15).to(user)
+  #     is_expected.to(
+  #       consent_view(:department)
+  #         .with_conditions(department_id: 15)
+  #         .to(user)
+  #     )
   #   end
   #   it { is_expected.to consent_action(:read) }
   #   it { is_expected.to consent_action(:update).with_views(:department) }
@@ -29,79 +36,12 @@ module Consent
   # Find more examples at:
   # https://github.com/powerhome/consent
   module Rspec
-    extend RSpec::Matchers::DSL
-
-    matcher :consent_action do |action_key|
-      chain :with_views do |*views|
-        @views = views
-      end
-
-      match do |subject_key|
-        action = Consent.find_action(subject_key, action_key)
-        if action && @views
-          values_match?(action.view_keys.sort, @views.sort)
-        else
-          !action.nil?
-        end
-      end
-
-      failure_message do |subject_key|
-        action = Consent.find_action(subject_key, action_key)
-        message = format(
-          'expected %<skey>s (%<sclass>s) to provide action %<action>s',
-          skey: subject_key.to_s, sclass: subject.class, action: action_key
-        )
-
-        if action && @views
-          format(
-            '%<message>s with views %<views>s, but actual views are %<keys>p',
-            message: message, views: @views, keys: action.view_keys
-          )
-        else
-          message
-        end
-      end
+    def consent_view(view_key, conditions = nil)
+      ConsentView.new(view_key, conditions)
     end
 
-    matcher :consent_view do |view_key, conditions|
-      chain :to do |*context|
-        @context = context
-      end
-
-      match do |subject_key|
-        view = Consent.find_view(subject_key, view_key)
-        if conditions
-          view&.conditions(*@context).eql?(conditions)
-        else
-          !view.nil?
-        end
-      end
-
-      failure_message do |subject_key|
-        view = Consent.find_view(subject_key, view_key)
-        message = format(
-          'expected %<skey>s (%<sclass>s) to provide view %<view>s with` \
-          `%<conditions>p, but',
-          skey: subject_key.to_s, sclass: subject.class,
-          view: view_key, conditions: conditions
-        )
-
-        if view && conditions
-          actual_conditions = view.conditions(*@context)
-          format(
-            '%<message>s conditions are %<conditions>p',
-            message: message, conditions: actual_conditions
-          )
-        else
-          actual_views = Consent.find_subjects(subject_key)
-                                .map(&:views)
-                                .map(&:keys).flatten
-          format(
-            '%<message>s available views are %<views>p',
-            message: message, views: actual_views
-          )
-        end
-      end
+    def consent_action(action_key)
+      ConsentAction.new(action_key)
     end
   end
 end

data/lib/consent/subject.rb

@@ -10,14 +10,5 @@ module Consent
       @actions = []
       @views = Consent.default_views.clone
     end
-
-    def permission_key
-      ActiveSupport::Inflector.underscore(@key.to_s).to_sym
-    end
-
-    def view_for(action, key)
-      view = @views.keys & action.view_keys & [key]
-      @views[view.first] || @views[action.default_view]
-    end
   end
 end

data/lib/consent/subject_coder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Consent
+  # Coder for ability subjects
+  module SubjectCoder
+  module_function
+
+    # Loads the serialized key (snake case string) as a valid
+    # permission subject (a constant or a symbol)
+    #
+    # @param key [String] snake case string representing a subject
+    # @return [Module,Class,Symbol]
+    def load(key)
+      return nil unless key
+
+      constant = key.camelize.safe_constantize
+      constant.is_a?(Class) ? constant : key.to_sym
+    end
+
+    # Dumps a serialized key (snake case string) from a valid
+    # permission subject (a constant or a symbol)
+    #
+    # @param key [Module,Class,Symbol] the subject key
+    # @return [String]
+    def dump(key)
+      key.to_s.underscore
+    end
+  end
+end

data/lib/consent/symbol_adapter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CanYouReally
+  # @private
+  class SymbolAdapter < ::CanCan::ModelAdapters::AbstractAdapter
+    def self.for_class?(subject)
+      subject.is_a?(Symbol) || subject == Symbol
+    end
+
+    def self.override_conditions_hash_matching?(_subject, _conditions)
+      true
+    end
+
+    def self.matches_conditions_hash?(_subject, _conditions)
+      true
+    end
+  end
+end

data/lib/consent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Consent
-  VERSION = '0.6.0'
+  VERSION = "2.0.0"
 end

data/lib/consent.rb

@@ -1,20 +1,30 @@
 # frozen_string_literal: true
 
-require 'consent/version'
-require 'consent/subject'
-require 'consent/view'
-require 'consent/action'
-require 'consent/dsl'
-require 'consent/permission'
-require 'consent/permissions'
-require 'consent/ability' if defined?(CanCan)
-require 'consent/railtie' if defined?(Rails)
+require "cancancan"
+
+require "consent/ability"
+require "consent/action"
+require "consent/dsl"
+require "consent/model_additions"
+require "consent/reloader"
+require "consent/subject_coder"
+require "consent/subject"
+require "consent/symbol_adapter"
+require "consent/version"
+require "consent/view"
 
 # Consent makes defining permissions easier by providing a clean,
-# concise DSL for authorization so that all abilities do not have
-# to be in your `Ability` class.
+# concise DSL for authorization so that your `Ability` isn't bloated
+# with all logic.
 module Consent
   FULL_ACCESS = %w[1 true].freeze
+  NO_ACCESS = :no_access
+
+  # Custom table_name_prefix for the Consent tables.
+  # Default: "consent_"
+  cattr_accessor(:table_name_prefix) { "consent_" }
+
+  ViewNotFound = Class.new(StandardError)
 
   # Default views available to every permission
   #
@@ -38,7 +48,7 @@ module Consent
   #
   # @return [Array<Consent::Subject>]
   def self.find_subjects(subject_key)
-    @subjects.find_all do |subject|
+    subjects.find_all do |subject|
       subject.key.eql?(subject_key)
     end
   end
@@ -47,21 +57,20 @@ module Consent
   #
   # @return [Consent::Action,nil]
   def self.find_action(subject_key, action_key)
-    Consent.find_subjects(subject_key)
-           .map(&:actions).flatten
-           .find do |action|
-             action.key.eql?(action_key)
-           end
+    find_subjects(subject_key)
+      .flat_map(&:actions)
+      .find do |action|
+        action.key.eql?(action_key)
+      end
   end
 
   # Finds a view within a subject context
   #
   # @return [Consent::View,nil]
-  def self.find_view(subject_key, view_key)
-    views = Consent.find_subjects(subject_key)
-                   .map(&:views)
-                   .reduce({}, &:merge)
-    views[view_key]
+  def self.find_view(subject_key, action_key, view_key)
+    find_action(subject_key, action_key)&.then do |action|
+      action.views[view_key] || raise(Consent::ViewNotFound)
+    end
   end
 
   # Loads all permission (ruby) files from the given directory
@@ -69,9 +78,9 @@ module Consent
   #
   # @param paths [Array<String,#to_s>] paths where the ruby files are located
   # @param mechanism [:require,:load] mechanism to load the files
-  def self.load_subjects!(paths, mechanism = :require)
-    permission_files = paths.map { |dir| File.join(dir, '*.rb') }
-    Dir[*permission_files].each(&Kernel.method(mechanism))
+  def self.load_subjects!(paths)
+    permission_files = paths.map { |dir| File.join(dir, "*.rb") }
+    Dir[*permission_files].each { |file| Kernel.load(file) }
   end
 
   # Defines a subject with the given key, label and options
@@ -90,11 +99,4 @@ module Consent
       DSL.build(subject, defaults, &block)
     end
   end
-
-  # Maps a permissions hash to a Consent::Permissions
-  #
-  # @return [Consent::Permissions]
-  def self.permissions(permissions)
-    Permissions.new(permissions)
-  end
 end

data/lib/generators/consent/permissions_generator.rb

@@ -2,19 +2,19 @@
 
 module Consent
   class PermissionsGenerator < Rails::Generators::NamedBase # :nodoc:
-    source_root File.expand_path('templates', __dir__)
+    source_root File.expand_path("templates", __dir__)
     argument :description, type: :string, required: false
 
     def create_permissions
       template(
-        'permissions.rb.erb',
-        "app/permissions/#{file_path}.rb",
+        "permissions.rb.erb",
+        "app/permissions/#{plural_file_name}.rb",
         assigns: { description: description }
       )
 
       template(
-        'permissions_spec.rb.erb',
-        "spec/permissions/#{file_path}_spec.rb"
+        "permissions_spec.rb.erb",
+        "spec/permissions/#{plural_file_name}_spec.rb"
       )
     end
   end

data/mkdocs.yml

@@ -0,0 +1,5 @@
+site_name: Consent
+nav:
+  - "Home": "README.md"
+plugins:
+  - techdocs-core

data/renovate.json

@@ -0,0 +1,18 @@
+{
+  "extends": ["config:base", "group:allNonMajor"],
+  "lockFileMaintenance": {
+    "enabled": true
+  },
+  "labels": ["dependencies"],
+  "timezone": "America/New_York",
+  "packageRules": [
+    {
+      "matchUpdateTypes": ["minor", "patch", "pin", "digest"],
+      "automerge": true
+    },
+    {
+      "matchDepTypes": ["devDependencies"],
+      "automerge": true
+    }
+  ]
+}