phalanx 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e3cae5ca06701db7bcbae49089f451412001f4c9f87f178d13b4ae9750a44a35
+  data.tar.gz: 738418d35debd75d1f09a5707b237bb1bd946454c0dac2f5094b8228fd3bcc22
+SHA512:
+  metadata.gz: 46825966362b53eb137632b340291404f2a4a960476c4d9a202869a8b621a990820107fd307be08b029841b1b48405054b6794b3aa4f9d1cb79e6671ed2acdc8
+  data.tar.gz: d4e567ef908b83eac76aaf19aa1ea2fe1079eb52240faefceef4308f4c5876b761b9fa5896858cdac288ceddb237ba6d7efd60d6e2a66be4b1cc74b28e192f01

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Minty Fresh
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,28 @@
+# Phalanx
+Short description and motivation.
+
+## Usage
+How to use my plugin.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "phalanx"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install phalanx
+```
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,9 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+require 'bundler/gem_tasks'

data/app/controllers/phalanx/application_controller.rb

@@ -0,0 +1,7 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  class ApplicationController < ActionController::API
+  end
+end

data/app/jobs/phalanx/application_job.rb

@@ -0,0 +1,7 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/models/concerns/phalanx/permission_assignable.rb

@@ -0,0 +1,79 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  module PermissionAssignable
+    extend T::Sig
+    extend T::Helpers
+    extend ActiveSupport::Concern
+
+    requires_ancestor { ActiveRecord::Base }
+
+    included do
+      T.bind(self, T.class_of(ActiveRecord::Base))
+
+      has_many :permission_assignments, as: :assignable, autosave: true, class_name: 'Phalanx::PermissionAssignment',
+                                        dependent: :destroy, inverse_of: :assignable
+    end
+
+    module ClassMethods
+      extend T::Sig
+
+      sig { params(scopes: String).void }
+      def permitted_permission_scopes(*scopes)
+        T.bind(self, T.class_of(ActiveRecord::Base))
+        define_method(:permitted_permission_scopes) { scopes }
+      end
+    end
+
+    mixes_in_class_methods ClassMethods
+
+    sig { returns(T::Set[Phalanx::Permission]) }
+    def permissions
+      T.let(T.unsafe(self).permission_assignments, T::Enumerable[Phalanx::PermissionAssignment])
+        .reject { |assignment| assignment.marked_for_destruction? || !assignment.permission_scope_supported? }
+        .filter_map(&:permission)
+        .flat_map(&:with_implied_permissions)
+        .to_set
+    end
+
+    sig { params(permissions: T::Enumerable[Phalanx::Permission]).void }
+    def permissions=(permissions)
+      permission_ids = permissions.flat_map(&:with_implied_permissions).to_set(&:id)
+
+      T.unsafe(self).permission_assignments.each do |permission_assignment|
+        next if permission_assignment.marked_for_destruction?
+
+        if permission_ids.include?(permission_assignment.permission_id)
+          permission_ids.delete(permission_assignment.permission_id)
+        else
+          permission_assignment.mark_for_destruction
+        end
+      end
+
+      permission_ids.each do |permission_id|
+        T.unsafe(self).permission_assignments.build(permission_id:)
+      end
+    end
+
+    sig { returns(T::Boolean) }
+    def permission_assignments_changed?
+      T.unsafe(self).permission_assignments.target.any?(&:changed_for_autosave?)
+    end
+
+    sig { overridable.returns(T.nilable(T.any(String, T::Enumerable[String]))) }
+    def permitted_permission_scopes
+      nil
+    end
+
+    sig { params(scope: String).returns(T::Boolean) }
+    def permission_scope_supported?(scope)
+      case (scopes = permitted_permission_scopes)
+      when Enumerable then scopes.include?(scope)
+      when String then scopes == scope
+      when nil then true
+      else T.absurd(scopes)
+      end
+    end
+  end
+end

data/app/models/phalanx/application_record.rb

@@ -0,0 +1,8 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/phalanx/permission_assignment.rb

@@ -0,0 +1,65 @@
+# typed: strict
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: phalanx_permission_assignments
+#
+#  id              :integer          not null, primary key
+#  assignable_type :string           not null
+#  created_at      :datetime         not null
+#  updated_at      :datetime         not null
+#  assignable_id   :bigint           not null
+#  permission_id   :string           not null
+#
+# Indexes
+#
+#  idx_on_assignable_type_assignable_id_permission_id_db35db88c3  (assignable_type,assignable_id,permission_id) UNIQUE
+#  index_phalanx_permission_assignments_on_assignable             (assignable_type,assignable_id)
+#  index_phalanx_permission_assignments_on_permission_id          (permission_id)
+#
+module Phalanx
+  class PermissionAssignment < ApplicationRecord
+    extend T::Sig
+
+    belongs_to :assignable, polymorphic: true
+
+    validates :permission_id, presence: true
+
+    validate :permission_must_have_supported_permission_scope
+
+    scope :stale, -> { where.not(permission_id: Phalanx.permission_class.values.map(&:id)) }
+
+    sig { returns(T::Boolean) }
+    def stale?
+      permission_id.present? && permission.nil?
+    end
+
+    sig { returns(T.nilable(Phalanx::Permission)) }
+    def permission
+      permission_id.present? ? Phalanx.permission_class[permission_id] : nil
+    end
+
+    sig { params(permission: Phalanx::Permission).void }
+    def permission=(permission)
+      self.permission_id = permission.id
+    end
+
+    sig { returns(T::Boolean) }
+    def permission_scope_supported?
+      return false if (assignable = self.assignable).nil? || (permission = self.permission).nil?
+
+      assignable.permission_scope_supported?(permission.scope)
+    end
+
+  private
+
+    sig { void }
+    def permission_must_have_supported_permission_scope
+      return if (assignable = self.assignable).nil? || (permission = self.permission).nil?
+      return if permission_scope_supported?
+
+      errors.add(:permission, :unsupported_permission_scope, scope: permission.scope)
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,6 @@
+# typed: false
+# frozen_string_literal: true
+
+Phalanx::Engine.routes.draw do
+  # No routes yet
+end

data/db/migrate/20260216223657_create_phalanx_permission_assignments.rb

@@ -0,0 +1,21 @@
+# typed: true
+# frozen_string_literal: true
+
+class CreatePhalanxPermissionAssignments < ActiveRecord::Migration[8.1]
+  extend T::Sig
+
+  include Phalanx::MigrationExtensions
+
+  sig { void }
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :phalanx_permission_assignments, id: primary_key_type do |t|
+      t.belongs_to :assignable, polymorphic: true, null: false, type: foreign_key_type
+      t.string     :permission_id, null: false, index: true
+      t.timestamps default: -> { 'CURRENT_TIMESTAMP' }
+
+      t.index %i[assignable_type assignable_id permission_id], unique: true
+    end
+  end
+end

data/lib/generators/phalanx/install/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Installs Phalanx, creating a default initializer file.
+
+Example:
+    bin/rails generate phalanx:install
+
+    This will create:
+        config/initializers/phalanx.rb

data/lib/generators/phalanx/install/install_generator.rb

@@ -0,0 +1,12 @@
+# typed: true
+# frozen_string_literal: true
+
+module Phalanx
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('templates', __dir__)
+
+    def create_initializer
+      template 'initializer.rb', 'config/initializers/phalanx.rb'
+    end
+  end
+end

data/lib/generators/phalanx/install/templates/initializer.rb

@@ -0,0 +1,25 @@
+# typed: true
+# frozen_string_literal: true
+
+Phalanx.configure do |config|
+  # To change the name of the permission class, you can specify a custom class name.
+  #
+  # config.permission_class_name = 'Permission'
+
+  # To change the location of the permission class file, you can specify a custom file path.
+  # This should match the class name specified in `config.permission_class_name`
+  # for the class loader to be able to find the class.
+  #
+  # config.permission_file_path = Rails.root.join('lib/permission.rb')
+
+  # To change the location from which permission files are loaded, you can specify a custom glob pattern.
+  # Multiple patterns can be specified if needed.
+  #
+  # config.permission_file_paths = [
+  #   Rails.root.join('config/permissions/**/*.{yml,yaml}'),
+  # ]
+
+  # If extending the permissions DSL, you can specify your own custom JSON schema file.
+  #
+  # config.schema_file_path = Rails.root.join('config/permissions-schema.json')
+end

data/lib/phalanx/config.rb

@@ -0,0 +1,28 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  class Config
+    extend T::Sig
+
+    sig { returns(Pathname) }
+    attr_accessor :schema_file_path
+
+    sig { returns(T::Array[Pathname]) }
+    attr_accessor :permission_file_paths
+
+    sig { returns(Pathname) }
+    attr_accessor :permission_file_path
+
+    sig { returns(String) }
+    attr_accessor :permission_class_name
+
+    sig { void }
+    def initialize
+      @schema_file_path = T.let(T.unsafe(Phalanx::Engine).root.join('schema.json'), Pathname)
+      @permission_file_paths = T.let([Rails.root.join('config/permissions/**/*.{yml,yaml}')], T::Array[Pathname])
+      @permission_file_path = T.let(Rails.root.join('lib/permission.rb'), Pathname)
+      @permission_class_name = T.let('Permission', String)
+    end
+  end
+end

data/lib/phalanx/engine.rb

@@ -0,0 +1,17 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'rails'
+
+module Phalanx
+  class Engine < ::Rails::Engine
+    isolate_namespace Phalanx
+
+    config.generators.api_only = true
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.fixture_replacement :factory_bot
+    end
+  end
+end

data/lib/phalanx/error.rb

@@ -0,0 +1,7 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  class Error < StandardError
+  end
+end

data/lib/phalanx/generator/dsl.rb

@@ -0,0 +1,93 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  class Generator
+    class DSL
+      extend T::Sig
+
+      SPACES_PER_INDENT = 2
+
+      sig { void }
+      def initialize
+        @buffer = T.let([], T::Array[String])
+        @indent_level = T.let(0, Integer)
+      end
+
+      sig { returns(String) }
+      def generate
+        @buffer.join
+      end
+
+      sig { params(text: String).returns(DSL) }
+      def comment(text)
+        text.lines.each do |line|
+          @buffer << indented("# #{line.strip}\n")
+        end
+        self
+      end
+
+      sig { returns(DSL) }
+      def newline
+        @buffer << "\n"
+        self
+      end
+
+      sig do
+        params(name: String, superclass: T.nilable(String), block: T.nilable(T.proc.params(dsl: DSL).void))
+          .returns(DSL)
+      end
+      def class(name, superclass: nil, &block)
+        @buffer << indented("class #{name}")
+        @buffer << " < #{superclass}" if superclass
+        @buffer << "\n"
+        with_indent(&block)
+        @buffer << indented('end')
+        @buffer << "\n"
+        self
+      end
+
+      sig { params(names: String).returns(DSL) }
+      def include(*names)
+        @buffer << indented("include #{names.join(', ')}\n")
+        self
+      end
+
+      sig { params(block: T.nilable(T.proc.params(dsl: DSL).void)).returns(DSL) }
+      def enums(&block)
+        @buffer << indented("enums do\n")
+        with_indent(&block)
+        @buffer << indented("end\n")
+        self
+      end
+
+      sig { params(name: String, attributes: T::Hash[String, T.untyped]).returns(DSL) }
+      def enum(name, attributes)
+        @buffer << indented("#{name} = new(\n")
+        with_indent do
+          attributes.each do |key, value|
+            @buffer << indented("#{key.inspect} => #{value.inspect},\n")
+          end
+        end
+        @buffer << indented(")\n")
+        self
+      end
+
+    private
+
+      sig { params(step: Integer, block: T.nilable(T.proc.params(dsl: DSL).void)).returns(DSL) }
+      def with_indent(step = 1, &block) # rubocop:disable Metrics/UnusedMethodArgument
+        @indent_level += step
+        yield self if block_given?
+        self
+      ensure
+        @indent_level -= step
+      end
+
+      sig { params(text: String).returns(String) }
+      def indented(text)
+        (' ' * (@indent_level * SPACES_PER_INDENT)) + text
+      end
+    end
+  end
+end

data/lib/phalanx/generator.rb

@@ -0,0 +1,91 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'phalanx/generator/dsl'
+
+module Phalanx
+  class Generator
+    extend T::Sig
+
+    MAGIC_COMMENT = <<~MAGIC_COMMENT
+      typed: strict
+      frozen_string_literal: true
+    MAGIC_COMMENT
+
+    HEADER = <<~HEADER
+      GENERATED FILE - DO NOT MODIFY
+
+      This file was generated by Phalanx.
+      Use `rails phalanx:generate` to regenerate this file.
+    HEADER
+
+    sig { params(permission_groups: T::Array[Parser::PermissionGroup], output_class_name: String, output_path: Pathname).void }
+    def initialize(permission_groups, output_class_name:, output_path:)
+      @permission_groups = permission_groups
+      @output_class_name = output_class_name
+      @output_path = output_path
+      @dsl = T.let(DSL.new, DSL)
+    end
+
+    sig { returns(T::Boolean) }
+    def stale?
+      # Early check if file is missing
+      return true unless File.exist?(@output_path)
+
+      file = Tempfile.new(['permission', '.rb'])
+      generate_permissions_class
+      file.write(@dsl.generate)
+      file.flush
+
+      !FileUtils.identical?(@output_path, T.must(file.path))
+    ensure
+      file&.close
+    end
+
+    sig { void }
+    def generate
+      file = File.open(@output_path, 'w')
+      generate_permissions_class
+      file.write(@dsl.generate)
+    ensure
+      file&.close
+    end
+
+  private
+
+    sig { void }
+    def generate_permissions_class
+      @dsl.comment(MAGIC_COMMENT)
+      @dsl.newline
+      @dsl.comment(HEADER)
+      @dsl.class(@output_class_name, superclass: 'T::Enum') do |dsl|
+        dsl.include('Phalanx::Permission')
+        dsl.enums do
+          @permission_groups.each do |permission_group|
+            generate_enums_values_for_permission_group(dsl, permission_group)
+          end
+        end
+      end
+    end
+
+    sig { params(dsl: DSL, permission_group: Parser::PermissionGroup).returns(DSL) }
+    def generate_enums_values_for_permission_group(dsl, permission_group)
+      dsl.comment("Permissions for #{permission_group.subject}")
+      dsl.newline
+      permission_group.permissions.each do |permission|
+        dsl.comment(T.must(permission.description).squish) if permission.description.present?
+        dsl.enum(
+          permission.constant_name, {
+            id: permission.id,
+            subject: permission_group.subject,
+            name: permission.name,
+            scope: permission.scope,
+            description: permission.description,
+            implies: permission.implies,
+          }
+        )
+      end
+      dsl.newline
+    end
+  end
+end

data/lib/phalanx/migration_extensions.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  module MigrationExtensions
+    extend T::Sig
+
+  private
+
+    sig { returns([T.any(Symbol, String), T.any(Symbol, String)]) }
+    def primary_and_foreign_key_types
+      config = Rails.configuration.generators
+      setting = config.options[config.orm][:primary_key_type]
+
+      primary_key_type = setting || :primary_key
+      foreign_key_type = setting || :bigint
+
+      [primary_key_type, foreign_key_type]
+    end
+  end
+end

data/lib/phalanx/parser/cycle_validator.rb

@@ -0,0 +1,128 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  class Parser
+    # Validates that permissions do not form a cycle by implication.
+    class CycleValidator
+      extend T::Sig
+
+      class CycleError < Phalanx::Error
+        extend T::Sig
+
+        sig { returns(T::Array[T::Array[String]]) }
+        attr_reader :cycles
+
+        sig { params(cycles: T::Array[T::Array[String]]).void }
+        def initialize(cycles)
+          super(build_message(cycles))
+
+          @cycles = cycles
+        end
+
+      private
+
+        sig { params(cycles: T::Array[T::Array[String]]).returns(String) }
+        def build_message(cycles)
+          cycle_descriptions = cycles.map.with_index(1) do |cycle, index|
+            "  #{index}. #{cycle.join(' -> ')}"
+          end
+
+          [
+            'Permission implication cycles detected:',
+            *cycle_descriptions,
+          ].join("\n")
+        end
+      end
+
+      sig { params(permission_groups: T::Array[Parser::PermissionGroup]).void }
+      def validate(permission_groups)
+        # Build a graph: permission_id -> array of implied permission_ids
+        graph = T.let({}, T::Hash[String, T::Array[String]])
+
+        permission_groups.each do |permission_group|
+          permission_group.permissions.each do |permission|
+            graph[permission.id] = permission.implies
+          end
+        end
+
+        cycles = find_all_cycles(graph)
+
+        raise CycleError, cycles if cycles.any?
+      end
+
+    private
+
+      sig { params(graph: T::Hash[String, T::Array[String]]).returns(T::Array[T::Array[String]]) }
+      def find_all_cycles(graph)
+        # Track global visited state and current path
+        visited = T.let(Set.new, T::Set[String])
+        path = T.let([], T::Array[String])
+        path_set = T.let(Set.new, T::Set[String])
+        cycles = T.let([], T::Array[T::Array[String]])
+
+        graph.each_key do |node|
+          next if visited.include?(node)
+
+          dfs(node, graph, visited, path, path_set, cycles)
+        end
+
+        # Normalize cycles to remove duplicates (same cycle starting from different points)
+        normalize_cycles(cycles)
+      end
+
+      sig do
+        params(
+          node: String,
+          graph: T::Hash[String, T::Array[String]],
+          visited: T::Set[String],
+          path: T::Array[String],
+          path_set: T::Set[String],
+          cycles: T::Array[T::Array[String]]
+        ).void
+      end
+      def dfs(node, graph, visited, path, path_set, cycles) # rubocop:disable Metrics/ParameterLists
+        visited.add(node)
+        path.push(node)
+        path_set.add(node)
+
+        neighbors = graph.fetch(node, [])
+        neighbors.each do |neighbor|
+          if path_set.include?(neighbor)
+            # Found a cycle - extract it from the path
+            cycle_start_index = T.must(path.index(neighbor))
+            cycle = [*path[cycle_start_index..], neighbor]
+            cycles << cycle
+          elsif visited.exclude?(neighbor)
+            dfs(neighbor, graph, visited, path, path_set, cycles)
+          end
+        end
+
+        path.pop
+        path_set.delete(node)
+      end
+
+      sig { params(cycles: T::Array[T::Array[String]]).returns(T::Array[T::Array[String]]) }
+      def normalize_cycles(cycles)
+        seen = T.let(Set.new, T::Set[String])
+
+        cycles.select do |cycle|
+          # Remove the duplicate last element for normalization
+          cycle_nodes = cycle[0...-1] || []
+
+          # Rotate to start from the smallest element for consistent comparison
+          min_index = cycle_nodes.each_with_index.min_by { |node, _| node }&.last || 0
+          rotated = cycle_nodes.rotate(min_index)
+          normalized = rotated.join(' -> ')
+
+          if seen.include?(normalized)
+            false
+          else
+            seen.add(normalized)
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phalanx/parser/permission.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  class Parser
+    class Permission < T::Struct
+      extend T::Sig
+
+      const :id, String
+      const :name, String
+      const :scope, T.nilable(String)
+      const :description, T.nilable(String)
+      const :implies, T::Array[String]
+
+      sig { returns(String) }
+      def constant_name
+        id.tr('.', '_').upcase
+      end
+    end
+  end
+end

data/lib/phalanx/parser/permission_group.rb

@@ -0,0 +1,12 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  class Parser
+    class PermissionGroup < T::Struct
+      const :subject, String
+      const :scope, T.nilable(String)
+      const :permissions, T::Array[Parser::Permission]
+    end
+  end
+end

data/lib/phalanx/parser/schema_validator.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'json-schema'
+
+module Phalanx
+  class Parser
+    class SchemaValidator
+      extend T::Sig
+
+      sig { params(schema_file_path: T.any(String, Pathname)).void }
+      def initialize(schema_file_path)
+        @schema_file_path = schema_file_path
+        @schema = T.let(JSON.load_file(schema_file_path), T.untyped)
+      end
+
+      sig { params(permissions_data: T.untyped).void }
+      def validate(permissions_data)
+        JSON::Validator.validate!(@schema, permissions_data)
+      end
+    end
+  end
+end

data/lib/phalanx/parser.rb

@@ -0,0 +1,52 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'phalanx/parser/cycle_validator'
+require 'phalanx/parser/permission'
+require 'phalanx/parser/permission_group'
+require 'phalanx/parser/schema_validator'
+
+module Phalanx
+  class Parser
+    extend T::Sig
+
+    sig { params(schema_file_path: T.any(String, Pathname)).void }
+    def initialize(schema_file_path:)
+      @schema_validator = T.let(SchemaValidator.new(schema_file_path), SchemaValidator)
+      @cycle_validator = T.let(CycleValidator.new, CycleValidator)
+    end
+
+    sig { params(file_paths: T::Array[T.any(String, Pathname)]).returns(T::Array[PermissionGroup]) }
+    def parse(file_paths)
+      permission_groups = file_paths.map do |file_path|
+        permission_data = YAML.load_file(file_path)
+        @schema_validator.validate(permission_data)
+
+        build_permission_group(permission_data)
+      end
+
+      @cycle_validator.validate(permission_groups)
+
+      permission_groups
+    end
+
+  private
+
+    sig { params(group_data: T::Hash[String, T.untyped]).returns(PermissionGroup) }
+    def build_permission_group(group_data)
+      PermissionGroup.new(
+        subject: group_data['subject'],
+        scope: group_data['scope'],
+        permissions: group_data['permissions'].map do |permission_id, permission_data|
+          Permission.new(
+            id: permission_id,
+            name: permission_data['name'],
+            scope: permission_data['scope'] || group_data['scope'],
+            description: permission_data['description'],
+            implies: [*permission_data['implies']]
+          )
+        end
+      )
+    end
+  end
+end

data/lib/phalanx/permission.rb

@@ -0,0 +1,132 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  module Permission
+    extend T::Sig
+    extend T::Helpers
+
+    requires_ancestor { T::Enum }
+
+    module ClassMethods
+      extend T::Sig
+      extend T::Helpers
+      extend T::Generic
+
+      has_attached_class!(:out) { { upper: Phalanx::Permission } }
+
+      # An index of all permissions mapped by their ID.
+      sig { returns(T::Hash[String, T.attached_class]) }
+      def permissions_by_id
+        @permissions_by_id ||= T.let(
+          T.unsafe(self).values.index_by(&:id).freeze,
+          T.nilable(T::Hash[String, T.attached_class])
+        )
+      end
+
+      # An index of all permissions mapped by their subject.
+      sig { returns(T::Hash[String, T::Array[T.attached_class]]) }
+      def permissions_by_subject
+        @permissions_by_subject ||= T.let(
+          T.unsafe(self).values.group_by(&:subject).freeze,
+          T.nilable(T::Hash[String, T::Array[T.attached_class]])
+        )
+      end
+
+      # An index of all permissions mapped by the IDs of the permissions that imply them.
+      # NOTE: This is the inverse of the `implies` property in the permissions configuration file.
+      sig { returns(T::Hash[String, T::Array[T.attached_class]]) }
+      def implying_permissions_by_id
+        @implying_permissions_by_id ||= T.let(
+          T.unsafe(self).values
+            .flat_map { |permission| permission.implied_permission_ids.map { |id| [id, permission] } }
+            .group_by { |id, _| id }
+            .transform_values { |permissions| permissions.map(&:last) }
+            .freeze,
+          T.nilable(T::Hash[String, T::Array[T.attached_class]])
+        )
+      end
+
+      # Finds a permission by its ID.
+      # @raise [Phalanx::PermissionNotFound] if the permission is not found.
+      sig { params(id: String).returns(T.attached_class) }
+      def find(id)
+        permissions_by_id[id] or Kernel.raise Phalanx::PermissionNotFound, id
+      end
+
+      # Finds a permission by its ID.
+      # Returns `nil` if the permission is not found.
+      sig { params(id: String).returns(T.nilable(T.attached_class)) }
+      def [](id) # rubocop:disable Rails/Delegate
+        permissions_by_id[id]
+      end
+    end
+
+    mixes_in_class_methods ClassMethods
+
+    # The unique identifier of the permission.
+    sig { returns(String) }
+    def id
+      serialize[:id]
+    end
+
+    # The subject that the permission belongs to.
+    # e.g. A model name ("User", "Post", "Comment") or a application area ("Dashboard", "Admin", "API")
+    sig { returns(String) }
+    def subject
+      serialize[:subject]
+    end
+
+    # The scope that the permission is part of.
+    # Useful when working with multiple distinct sets of permissions (e.g. Global vs. Subject-specific).
+    sig { returns(T.nilable(String)) }
+    def scope
+      serialize[:scope]
+    end
+
+    # A human-readable name of the permission.
+    sig { returns(String) }
+    def name
+      serialize[:name]
+    end
+
+    # A human-readable description of the permission.
+    sig { returns(T.nilable(String)) }
+    def description
+      serialize[:description]
+    end
+
+    # The list of permission IDs that are implied by having this permission.
+    sig { returns(T::Array[String]) }
+    def implied_permission_ids
+      serialize[:implies]
+    end
+
+    # The list of permissions that are implied by having this permission.
+    sig { returns(T::Array[Phalanx::Permission]) }
+    def implied_permissions
+      implied_permission_ids.map { |id| T.cast(self.class, ClassMethods[Permission]).find(id) }
+    end
+
+    # The list of permission IDs that imply this permission.
+    # This is the inverse of #implied_permission_ids.
+    sig { returns(T::Array[String]) }
+    def implying_permission_ids
+      implying_permissions.map(&:id)
+    end
+
+    # The list of permissions that imply this permission.
+    # This is the inverse of #implied_permissions.
+    sig { returns(T::Array[Phalanx::Permission]) }
+    def implying_permissions
+      T.cast(self.class, ClassMethods[Permission]).implying_permissions_by_id.fetch(id) { [] }
+    end
+
+    # The recursive list of permissions that are implied by having this permission, including this permission.
+    # If no permissions are implied by this permission, returns a list containing only itself.
+    sig { returns(T::Array[Phalanx::Permission]) }
+    def with_implied_permissions
+      [self, *implied_permissions.flat_map(&:with_implied_permissions)].uniq
+    end
+  end
+end

data/lib/phalanx/permission_not_found.rb

@@ -0,0 +1,18 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  class PermissionNotFound < Phalanx::Error
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_reader :id
+
+    sig { params(id: String).void }
+    def initialize(id)
+      super("Permission with id #{id.inspect} not found")
+
+      @id = id
+    end
+  end
+end

data/lib/phalanx/version.rb

@@ -0,0 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Phalanx
+  VERSION = '0.2.0'
+end

data/lib/phalanx.rb

@@ -0,0 +1,70 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+require 'phalanx/version'
+require 'phalanx/engine'
+
+require 'phalanx/config'
+require 'phalanx/error'
+require 'phalanx/generator'
+require 'phalanx/permission_not_found'
+require 'phalanx/parser'
+require 'phalanx/permission'
+
+module Phalanx
+  extend T::Sig
+
+  autoload :MigrationExtensions, 'phalanx/migration_extensions'
+
+  PermissionClass = T.type_alias do
+    T.all(
+      T.class_of(T::Enum),
+      T::Class[Phalanx::Permission],
+      Phalanx::Permission::ClassMethods[Phalanx::Permission]
+    )
+  end
+
+  sig { returns(Phalanx::Config) }
+  def self.config
+    @config ||= T.let(Phalanx::Config.new.freeze, T.nilable(Phalanx::Config))
+  end
+
+  sig { params(block: T.proc.params(config: Phalanx::Config).void).void }
+  def self.configure(&block)
+    config = self.config.dup
+    block.call(config) # rubocop:disable Performance/RedundantBlockCall
+    @config = config.freeze
+  end
+
+  sig { returns(T::Array[Pathname]) }
+  def self.permission_file_paths
+    config.permission_file_paths.flat_map { |path| Pathname.glob(path) }
+  end
+
+  sig { returns(PermissionClass) }
+  def self.permission_class
+    config.permission_class_name.safe_constantize or
+      raise NotImplementedError, "Permission class #{config.permission_class_name.inspect} not found; " \
+                                 'have you run `rails phalanx:generate`?'
+  end
+
+  sig { void }
+  def self.generate_permission_class
+    output_class_name = config.permission_class_name
+    output_path = config.permission_file_path
+
+    permission_groups = Parser.new(schema_file_path: config.schema_file_path).parse(permission_file_paths)
+    Generator.new(permission_groups, output_class_name:, output_path:).generate
+  end
+
+  sig { returns(T::Boolean) }
+  def self.permission_class_stale?
+    output_class_name = config.permission_class_name
+    output_path = config.permission_file_path
+
+    permission_groups = Parser.new(schema_file_path: config.schema_file_path).parse(permission_file_paths)
+    Generator.new(permission_groups, output_class_name:, output_path:).stale?
+  end
+end

data/lib/tasks/phalanx_tasks.rake

@@ -0,0 +1,19 @@
+# typed: false
+# frozen_string_literal: true
+
+namespace :phalanx do
+  desc 'Generate the permission class'
+  task generate: :environment do
+    Phalanx.generate_permission_class
+  end
+
+  desc 'Check if the permission class is stale'
+  task stale: :environment do
+    if Phalanx.permission_class_stale?
+      puts 'Permission class is stale'
+      exit 1
+    else
+      exit 0
+    end
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: phalanx
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Minty Fresh
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.1
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Fine-grained permissions for Rails + Sorbet.
+email:
+- 7896757+mintyfresh@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/phalanx/application_controller.rb
+- app/jobs/phalanx/application_job.rb
+- app/models/concerns/phalanx/permission_assignable.rb
+- app/models/phalanx/application_record.rb
+- app/models/phalanx/permission_assignment.rb
+- config/routes.rb
+- db/migrate/20260216223657_create_phalanx_permission_assignments.rb
+- lib/generators/phalanx/install/USAGE
+- lib/generators/phalanx/install/install_generator.rb
+- lib/generators/phalanx/install/templates/initializer.rb
+- lib/phalanx.rb
+- lib/phalanx/config.rb
+- lib/phalanx/engine.rb
+- lib/phalanx/error.rb
+- lib/phalanx/generator.rb
+- lib/phalanx/generator/dsl.rb
+- lib/phalanx/migration_extensions.rb
+- lib/phalanx/parser.rb
+- lib/phalanx/parser/cycle_validator.rb
+- lib/phalanx/parser/permission.rb
+- lib/phalanx/parser/permission_group.rb
+- lib/phalanx/parser/schema_validator.rb
+- lib/phalanx/permission.rb
+- lib/phalanx/permission_not_found.rb
+- lib/phalanx/version.rb
+- lib/tasks/phalanx_tasks.rake
+homepage: https://github.com/mintyfresh/phalanx
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/mintyfresh/phalanx
+  source_code_uri: https://github.com/mintyfresh/phalanx
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.8
+specification_version: 4
+summary: Fine-grained permissions for Rails + Sorbet.
+test_files: []