consent 1.0.1 → 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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'consent'
-RSpec::Support.require_rspec_support 'fuzzy_matcher'
+require "consent"
+RSpec::Support.require_rspec_support "fuzzy_matcher"
 
 module Consent
   module Rspec
@@ -35,25 +35,25 @@ module Consent
       end
 
       def failure_message
-        failure_message_base 'to'
+        failure_message_base "to"
       end
 
       def failure_message_when_negated
-        failure_message_base 'to not'
+        failure_message_base "to not"
       end
 
-      private
+    private
 
       def failure_message_base(failure) # rubocop:disable Metrics/MethodLength
         message = format(
-          'expected %<skey>s (%<sclass>s) %<failure> provide action %<action>s',
+          "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>s with views %<views>s, but actual views are %<keys>p",
             message: message, views: @views, keys: @action.views.keys
           )
         else

data/lib/consent/rspec/consent_view.rb

@@ -27,23 +27,20 @@ module Consent
       def matches?(subject_key)
         @subject_key = subject_key
         @target = Consent.find_subjects(subject_key)
-                         .map do |subject|
-                           subject.views[@view_key]&.conditions(*@context)
-                         end
-                         .compact
-                         .map(&method(:comparable_conditions))
+                         .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'
+        failure_message_base "to"
       end
 
       def failure_message_when_negated
-        failure_message_base 'to not'
+        failure_message_base "to not"
       end
 
-      private
+    private
 
       def comparable_conditions(conditions)
         return conditions.to_sql if conditions.respond_to?(:to_sql)
@@ -61,15 +58,15 @@ module Consent
 
         if @target.any?
           format(
-            '%<message>s conditions are %<conditions>p',
+            "%<message>s conditions are %<conditions>p",
             message: message, conditions: @target
           )
         else
-          actual_views = Consent.find_subjects(subject_key)
+          actual_views = Consent.find_subjects(@subject_key)
                                 .map(&:views)
                                 .map(&:keys).flatten
           format(
-            '%<message>s available views are %<views>p',
+            "%<message>s available views are %<views>p",
             message: message, views: actual_views
           )
         end

data/lib/consent/rspec.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require 'consent'
+require "consent"
 
-require_relative 'rspec/consent_action'
-require_relative 'rspec/consent_view'
+require_relative "rspec/consent_action"
+require_relative "rspec/consent_view"
 
 module Consent
   # RSpec helpers for consent. Given permissions are loaded,

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 = '1.0.1'
+  VERSION = "2.0.0"
 end

data/lib/consent.rb

@@ -1,17 +1,29 @@
 # frozen_string_literal: true
 
-require 'consent/version'
-require 'consent/subject'
-require 'consent/view'
-require 'consent/action'
-require 'consent/dsl'
-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
@@ -56,7 +68,7 @@ module Consent
   #
   # @return [Consent::View,nil]
   def self.find_view(subject_key, action_key, view_key)
-    find_action(subject_key, action_key)&.yield_self do |action|
+    find_action(subject_key, action_key)&.then do |action|
       action.views[view_key] || raise(Consent::ViewNotFound)
     end
   end
@@ -66,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

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

@@ -1,5 +1,18 @@
 {
-  "extends": [
-    "config:base"
+  "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
+    }
   ]
 }