role_fu 0.1.0

data/lib/role_fu/resourceable.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module RoleFu
+  # Resourceable concern - provides resource management for models with roles
+  module Resourceable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :roles,
+        as: :resource,
+        dependent: :destroy,
+        class_name: RoleFu.configuration.role_class_name
+    end
+
+    module ClassMethods
+      # Find roles defined on any instance of this resource class
+      # @param role_name [String, Symbol, nil] Filter by role name
+      # @param user [User, nil] Filter by user
+      # @return [ActiveRecord::Relation] Roles
+      def find_roles(role_name = nil, user = nil)
+        RoleFu.role_class.table_name
+        query = RoleFu.role_class.where(resource_type: name)
+        query = query.where(name: role_name.to_s) if role_name
+        query = query.joins(:users).where(RoleFu.user_class.table_name => {id: user.id}) if user
+        query
+      end
+
+      # Find resources that have a specific role applied (to a user)
+      # @param role_name [String, Symbol] The role name
+      # @param user [User, nil] Filter by specific user having the role
+      # @return [ActiveRecord::Relation] Resources
+      def with_role(role_name, user = nil)
+        role_table = RoleFu.role_class.table_name
+
+        query = joins(:roles).where(role_table => {name: role_name.to_s})
+
+        if user
+          query = query.joins(roles: :users).where(RoleFu.user_class.table_name => {id: user.id})
+        end
+
+        query.distinct
+      end
+
+      # Find resources that do NOT have a specific role applied
+      # @param role_name [String, Symbol] The role name
+      # @param user [User, nil] Filter by user
+      # @return [ActiveRecord::Relation] Resources
+      def without_role(role_name, user = nil)
+        where.not(id: with_role(role_name, user).select(:id))
+      end
+    end
+
+    # Get roles applied to this resource instance (plus global class-level roles if any - though RoleFu focuses on instance roles)
+    # @return [ActiveRecord::Relation] Roles
+    def applied_roles
+      roles
+    end
+
+    # Get users with a specific role on this resource
+    # @param role_name [String, Symbol] The role name
+    # @return [ActiveRecord::Relation] Relation of users
+    def users_with_role(role_name)
+      role_table = RoleFu.role_class.table_name
+      user_class.joins(:roles)
+        .where(role_table => {name: role_name.to_s, resource_type: self.class.name, resource_id: id})
+        .distinct
+    end
+
+    # Get users with any role on this resource
+    # @param role_names [Array<String, Symbol>] Array of role names
+    # @return [ActiveRecord::Relation] Relation of users
+    def users_with_any_role(*role_names)
+      role_table = RoleFu.role_class.table_name
+      user_class.joins(:roles)
+        .where(role_table => {name: role_names.flatten.map(&:to_s), resource_type: self.class.name, resource_id: id})
+        .distinct
+    end
+
+    # Get users with all specified roles on this resource
+    # @param role_names [Array<String, Symbol>] Array of role names
+    # @return [Array<User>] Array of users
+    def users_with_all_roles(*role_names)
+      role_names = role_names.flatten.map(&:to_s)
+      role_table = RoleFu.role_class.table_name
+
+      user_class.joins(:roles)
+        .where(role_table => {name: role_names, resource_type: self.class.name, resource_id: id})
+        .group("#{user_class.table_name}.#{user_class.primary_key}")
+        .having("COUNT(DISTINCT #{role_table}.name) = ?", role_names.size)
+        .distinct
+    end
+
+    # Get all users with any role on this resource
+    # @return [ActiveRecord::Relation] Relation of users
+    def users_with_roles
+      role_table = RoleFu.role_class.table_name
+      user_class.joins(:roles)
+        .where(role_table => {resource_type: self.class.name, resource_id: id})
+        .distinct
+    end
+
+    # Get all role names defined for this resource
+    # @return [Array<String>] Array of role names
+    def available_roles
+      roles.pluck(:name).uniq
+    end
+
+    # Check if resource has any users with a specific role
+    # @param role_name [String, Symbol] The role name
+    # @return [Boolean] true if any user has this role
+    def has_role?(role_name)
+      roles.exists?(name: role_name.to_s)
+    end
+
+    # Count users with a specific role
+    # @param role_name [String, Symbol] The role name
+    # @return [Integer] Number of users
+    def count_users_with_role(role_name)
+      users_with_role(role_name).count
+    end
+
+    # Check if a specific user has a role on this resource
+    # @param user [User] The user
+    # @param role_name [String, Symbol] The role name
+    # @return [Boolean] true if user has the role
+    def user_has_role?(user, role_name)
+      return false if user.nil?
+
+      user.has_role?(role_name, self)
+    end
+
+    # Add a role to a user on this resource
+    # @param user [User] The user
+    # @param role_name [String, Symbol] The role name
+    # @return [Role] The role
+    def add_role_to_user(user, role_name)
+      user.add_role(role_name, self)
+    end
+
+    # Remove a role from a user on this resource
+    # @param user [User] The user
+    # @param role_name [String, Symbol] The role name
+    # @return [Array<Role>] The removed roles
+    def remove_role_from_user(user, role_name)
+      user.remove_role(role_name, self)
+    end
+
+    private
+
+    # Get the User class
+    # @return [Class] User class
+    def user_class
+      RoleFu.user_class
+    end
+  end
+end

data/lib/role_fu/role.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RoleFu
+  # Module for the Role model
+  module Role
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :role_assignments,
+        class_name: RoleFu.configuration.role_assignment_class_name,
+        dependent: :destroy
+      has_many :users,
+        through: :role_assignments,
+        class_name: RoleFu.configuration.user_class_name
+
+      belongs_to :resource, polymorphic: true, optional: true
+
+      validates :name, presence: true, uniqueness: {scope: [:resource_type, :resource_id]}
+    end
+  end
+end

data/lib/role_fu/role_assignment.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RoleFu
+  # Module for the RoleAssignment model
+  module RoleAssignment
+    extend ActiveSupport::Concern
+
+    included do
+      belongs_to :user, class_name: RoleFu.configuration.user_class_name
+      belongs_to :role, class_name: RoleFu.configuration.role_class_name
+
+      scope :global_roles, -> { joins(:role).where(RoleFu.role_class.table_name => {resource_type: nil, resource_id: nil}) }
+      scope :resource_specific, -> { joins(:role).where.not(RoleFu.role_class.table_name => {resource_type: nil}) }
+
+      after_destroy :cleanup_orphaned_role
+    end
+
+    private
+
+    def cleanup_orphaned_role
+      # If this record is being destroyed as part of role destruction,
+      # do not try to destroy the same role again.
+      return if destroyed_by_association&.active_record == RoleFu.role_class
+
+      # Delete role if it has no more users assigned
+      return if role.destroyed?
+
+      role.destroy if role.role_assignments.none?
+    end
+  end
+end

data/lib/role_fu/roleable.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+module RoleFu
+  # Roleable concern - provides role management for User model
+  module Roleable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :role_assignments,
+        class_name: RoleFu.configuration.role_assignment_class_name,
+        dependent: :destroy
+      has_many :roles,
+        through: :role_assignments,
+        class_name: RoleFu.configuration.role_class_name
+
+      class_attribute :role_fu_callbacks, default: {}
+    end
+
+    module ClassMethods
+      def role_fu_options(options = {})
+        self.role_fu_callbacks = options.slice(:before_add, :after_add, :before_remove, :after_remove)
+      end
+
+      # Find users with a specific role
+      # @param role_name [String, Symbol] The name of the role
+      # @param resource [ActiveRecord::Base, Class, nil, :any] The resource
+      # @return [ActiveRecord::Relation] Users with the role
+      def with_role(role_name, resource = nil)
+        role_table = RoleFu.role_class.table_name
+        RoleFu.role_assignment_class.table_name
+
+        query = joins(:roles).where(role_table => {name: role_name.to_s})
+
+        if resource.nil?
+          query.where(role_table => {resource_type: nil, resource_id: nil})
+        elsif resource == :any
+          query
+        elsif resource.is_a?(Class)
+          query.where(role_table => {resource_type: resource.to_s, resource_id: nil})
+        else
+          query.where(role_table => {resource_type: resource.class.name, resource_id: resource.id})
+        end.distinct
+      end
+
+      # Find users without a specific role
+      # @param role_name [String, Symbol] The name of the role
+      # @param resource [ActiveRecord::Base, Class, nil, :any] The resource
+      # @return [ActiveRecord::Relation] Users without the role
+      def without_role(role_name, resource = nil)
+        where.not(id: with_role(role_name, resource).select(:id))
+      end
+
+      # Find users with any of the specified roles
+      # @param args [Array<String, Symbol, Hash>] Roles to check
+      # @return [ActiveRecord::Relation] Users with any of the roles
+      def with_any_role(*args)
+        ids = []
+        args.each do |arg|
+          ids += if arg.is_a?(Hash)
+            with_role(arg[:name], arg[:resource]).pluck(:id)
+          else
+            with_role(arg).pluck(:id)
+          end
+        end
+        where(id: ids.uniq)
+      end
+
+      # Find users with all of the specified roles
+      # @param args [Array<String, Symbol, Hash>] Roles to check
+      # @return [ActiveRecord::Relation] Users with all of the roles
+      def with_all_roles(*args)
+        ids = nil
+        args.each do |arg|
+          current_ids = if arg.is_a?(Hash)
+            with_role(arg[:name], arg[:resource]).pluck(:id)
+          else
+            with_role(arg).pluck(:id)
+          end
+          ids = ids.nil? ? current_ids : ids & current_ids
+          return none if ids.empty?
+        end
+        where(id: ids)
+      end
+    end
+
+    # Add a role to the user
+    # @param role_name [String, Symbol] The name of the role
+    # @param resource [ActiveRecord::Base, Class, nil] The resource (organization, etc.) or nil for global role
+    # @return [Role] The role that was added
+    def add_role(role_name, resource = nil)
+      role = find_or_create_role(role_name, resource)
+
+      return role if roles.include?(role)
+
+      run_role_fu_callback(:before_add, role)
+      roles << role
+      run_role_fu_callback(:after_add, role)
+
+      role
+    end
+    alias_method :grant, :add_role
+
+    # Remove a role from the user
+    # @param role_name [String, Symbol] The name of the role
+    # @param resource [ActiveRecord::Base, Class, nil] The resource or nil for global role
+    # @return [Array<Role>] The roles that were removed
+    def remove_role(role_name, resource = nil)
+      roles_to_remove_relation = find_roles(role_name, resource)
+      return [] if roles_to_remove_relation.empty?
+
+      # Materialize before removing associations, because removing may trigger cleanup that deletes the role.
+      removed_roles = roles_to_remove_relation.to_a
+
+      removed_roles.each do |role|
+        run_role_fu_callback(:before_remove, role)
+        role_assignments.where(role_id: role.id).destroy_all
+        run_role_fu_callback(:after_remove, role)
+      end
+
+      removed_roles
+    end
+    alias_method :revoke, :remove_role
+
+    # Check if user has a specific role
+    # @param role_name [String, Symbol] The name of the role
+    # @param resource [ActiveRecord::Base, Class, nil, :any] The resource, nil for global, or :any for any resource
+    # @return [Boolean] true if user has the role
+    def has_role?(role_name, resource = nil)
+      return false if role_name.nil?
+
+      if resource == :any
+        roles.exists?(name: role_name.to_s)
+      else
+        find_roles(role_name, resource).any?
+      end
+    end
+
+    # Check if user has a specific role strictly (resource match must be exact, no globals overriding)
+    # Note: In RoleFu, has_role? is already strict about resource matching unless :any is passed,
+    # but this method explicitly bypasses any future global-fallback logic if we were to add it.
+    # Included for API compatibility.
+    # @param role_name [String, Symbol] The name of the role
+    # @param resource [ActiveRecord::Base, Class, nil] The resource
+    # @return [Boolean] true if user has the role strictly
+    def has_strict_role?(role_name, resource = nil)
+      has_role?(role_name, resource)
+    end
+
+    # Check if user only has this one role
+    # @param role_name [String, Symbol] The name of the role
+    # @param resource [ActiveRecord::Base, Class, nil] The resource
+    # @return [Boolean] true if user has this role and no others
+    def only_has_role?(role_name, resource = nil)
+      has_role?(role_name, resource) && roles.count == 1
+    end
+
+    # Check for role using preloaded association to avoid N+1
+    def has_cached_role?(role_name, resource = nil)
+      role_name = role_name.to_s
+      roles.to_a.any? do |role|
+        next false unless role.name == role_name
+
+        if resource == :any
+          true
+        elsif resource.is_a?(Class)
+          role.resource_type == resource.to_s && role.resource_id.nil?
+        elsif resource
+          role.resource_type == resource.class.name && role.resource_id == resource.id
+        else
+          role.resource_type.nil? && role.resource_id.nil?
+        end
+      end
+    end
+
+    # Get all role names for this user
+    # @param resource [ActiveRecord::Base, Class, nil] Filter by resource
+    # @return [Array<String>] Array of role names
+    def roles_name(resource = nil)
+      if resource
+        roles.where(resource: resource).pluck(:name)
+      else
+        roles.pluck(:name)
+      end
+    end
+
+    # Check if user has only global roles (no resource-specific roles)
+    # @return [Boolean] true if user has only global roles
+    def has_only_global_roles?
+      roles.where.not(resource_type: nil).empty?
+    end
+
+    # Check if user has any role (global or resource-specific)
+    # @param resource [ActiveRecord::Base, Class, nil] Filter by resource
+    # @return [Boolean] true if user has any role
+    def has_any_role?(resource = nil)
+      if resource
+        roles.exists?(resource: resource)
+      else
+        roles.exists?
+      end
+    end
+
+    # Check if user has all specified roles
+    # @param role_names [Array<String, Symbol>] Array of role names
+    # @param resource [ActiveRecord::Base, Class, nil] The resource
+    # @return [Boolean] true if user has all roles
+    def has_all_roles?(*role_names, resource: nil)
+      role_names.flatten.all? { |role_name| has_role?(role_name, resource) }
+    end
+
+    # Check if user has any of the specified roles
+    # @param role_names [Array<String, Symbol>] Array of role names
+    # @param resource [ActiveRecord::Base, Class, nil] The resource
+    # @return [Boolean] true if user has any of the roles
+    def has_any_role_of?(*role_names, resource: nil)
+      role_names.flatten.any? { |role_name| has_role?(role_name, resource) }
+    end
+
+    # Get all resources of a specific type where user has a role
+    # @param resource_class [Class] The resource class (e.g., Organization)
+    # @return [ActiveRecord::Relation] Relation of resources
+    def resources(resource_class)
+      resource_class.joins(:roles)
+        .merge(roles.where(resource_type: resource_class.name))
+        .distinct
+    end
+
+    private
+
+    # Find or create a role
+    # @param role_name [String, Symbol] The role name
+    # @param resource [ActiveRecord::Base, Class, nil] The resource
+    # @return [Role] The found or created role
+    def find_or_create_role(role_name, resource)
+      resource_type = resource_type_for(resource)
+      resource_id = resource_id_for(resource)
+
+      RoleFu.role_class.find_or_create_by(
+        name: role_name.to_s,
+        resource_type: resource_type,
+        resource_id: resource_id
+      )
+    end
+
+    # Find roles matching criteria
+    # @param role_name [String, Symbol] The role name
+    # @param resource [ActiveRecord::Base, Class, nil] The resource
+    # @return [ActiveRecord::Relation] Relation of matching roles
+    def find_roles(role_name, resource)
+      query = roles.where(name: role_name.to_s)
+
+      if resource.is_a?(Class)
+        query.where(resource_type: resource.to_s, resource_id: nil)
+      elsif resource
+        query.where(resource_type: resource.class.name, resource_id: resource.id)
+      else
+        query.where(resource_type: nil, resource_id: nil)
+      end
+    end
+
+    # Get resource type for a resource
+    # @param resource [ActiveRecord::Base, Class, nil] The resource
+    # @return [String, nil] The resource type
+    def resource_type_for(resource)
+      return nil if resource.nil?
+
+      resource.is_a?(Class) ? resource.to_s : resource.class.name
+    end
+
+    # Get resource id for a resource
+    # @param resource [ActiveRecord::Base, Class, nil] The resource
+    # @return [Integer, nil] The resource id
+    def resource_id_for(resource)
+      return nil if resource.nil? || resource.is_a?(Class)
+
+      resource.id
+    end
+
+    def run_role_fu_callback(callback_name, role)
+      method_name = role_fu_callbacks[callback_name]
+      return unless method_name
+
+      if method_name.is_a?(Proc)
+        instance_exec(role, &method_name)
+      elsif respond_to?(method_name, true)
+        send(method_name, role)
+      end
+    end
+  end
+end

data/lib/role_fu/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RoleFu
+  VERSION = "0.1.0"
+end

data/lib/role_fu.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/string/inflections"
+
+require_relative "role_fu/version"
+require_relative "role_fu/configuration"
+require_relative "role_fu/role"
+require_relative "role_fu/role_assignment"
+require_relative "role_fu/roleable"
+require_relative "role_fu/resourceable"
+
+module RoleFu
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/role_fu.rbs

@@ -0,0 +1,4 @@
+module RoleFu
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,173 @@
+--- !ruby/object:Gem::Specification
+name: role_fu
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexey Poimtsev
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: lefthook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: RoleFu provides explicit role management with Role and RoleAssignment
+  models, avoiding hidden HABTM tables. Supports scopes, resource-specific roles,
+  and cleaner architecture.
+email:
+- alexey.poimtsev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Appraisals
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- gemfiles/rails_7.0.gemfile
+- gemfiles/rails_7.0.gemfile.lock
+- gemfiles/rails_7.1.gemfile
+- gemfiles/rails_7.1.gemfile.lock
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_7.2.gemfile.lock
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.0.gemfile.lock
+- gemfiles/rails_8.1.gemfile
+- gemfiles/rails_8.1.gemfile.lock
+- lefthook.yml
+- lib/generators/role_fu/install_generator.rb
+- lib/generators/role_fu/role_fu_generator.rb
+- lib/generators/role_fu/templates/migration.rb.erb
+- lib/generators/role_fu/templates/role.rb.erb
+- lib/generators/role_fu/templates/role_assignment.rb.erb
+- lib/generators/role_fu/templates/role_fu.rb
+- lib/role_fu.rb
+- lib/role_fu/configuration.rb
+- lib/role_fu/resourceable.rb
+- lib/role_fu/role.rb
+- lib/role_fu/role_assignment.rb
+- lib/role_fu/roleable.rb
+- lib/role_fu/version.rb
+- sig/role_fu.rbs
+homepage: https://github.com/alec-c4/role_fu
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/alec-c4/role_fu
+  source_code_uri: https://github.com/alec-c4/role_fu
+  changelog_uri: https://github.com/alec-c4/role_fu/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.5
+specification_version: 4
+summary: A modern role management gem for Rails, replacing rolify.
+test_files: []