plutonium 0.13.3 → 0.14.1

data/lib/plutonium/core/controllers/entity_scoping.rb

@@ -1,6 +1,17 @@
+# frozen_string_literal: true
+
 module Plutonium
   module Core
     module Controllers
+      # EntityScoping module provides functionality for scoping controllers to specific entities.
+      #
+      # This module is designed to be included in controllers that need to operate within the context
+      # of a specific entity, such as a user's organization or a project.
+      #
+      # @example Usage in a controller
+      #   class MyController < ApplicationController
+      #     include Plutonium::Core::Controllers::EntityScoping
+      #   end
       module EntityScoping
         extend ActiveSupport::Concern
 
@@ -9,70 +20,117 @@ module Plutonium
           helper_method :current_scoped_entity
         end
 
-        private
-
+        # Checks if the current engine is scoped to an entity.
+        #
+        # @return [Boolean] true if scoped to an entity, false otherwise
         def scoped_to_entity?
           current_engine.scoped_to_entity?
         end
 
+        # Returns the strategy used for entity scoping.
+        #
+        # @return [Symbol] the scoping strategy
         def scoped_entity_strategy
           current_engine.scoped_entity_strategy
         end
 
-        def scoped_entity_class
-          ensure_legal_entity_scoping_method_access! :scoped_entity_class
+        # Returns the parameter key used for entity scoping.
+        #
+        # @return [Symbol] the parameter key
+        # @raise [NotImplementedError] if not scoped to an entity
+        def scoped_entity_param_key
+          ensure_legal_entity_scoping_method_access!(__method__)
+          current_engine.scoped_entity_param_key
+        end
 
+        # Returns the class of the scoped entity.
+        #
+        # @return [Class] the scoped entity class
+        # @raise [NotImplementedError] if not scoped to an entity
+        def scoped_entity_class
+          ensure_legal_entity_scoping_method_access!(__method__)
           current_engine.scoped_entity_class
         end
 
-        def scoped_entity_param_key
-          ensure_legal_entity_scoping_method_access! :scoped_entity_param_key
-
-          current_engine.scoped_entity_param_key
-        end
+        private
 
+        # Returns the session key used to store the scoped entity.
+        #
+        # @return [Symbol] the session key
+        # @raise [NotImplementedError] if not scoped to an entity
         def scoped_entity_session_key
-          ensure_legal_entity_scoping_method_access! :scoped_entity_session_key
-
+          ensure_legal_entity_scoping_method_access!(__method__)
           :"#{current_package.name.underscore}__scoped_entity_id"
         end
 
+        # Returns the current scoped entity for the request.
+        #
+        # @return [ActiveRecord::Base, nil] the current scoped entity or nil if not found
+        # @raise [NotImplementedError] if not scoped to an entity or strategy is unknown
         def current_scoped_entity
-          ensure_legal_entity_scoping_method_access! :current_scoped_entity
-
+          ensure_legal_entity_scoping_method_access!(__method__)
           return unless current_user.present?
 
-          @current_scoped_entity ||= case scoped_entity_strategy
+          @current_scoped_entity ||= fetch_current_scoped_entity
+        end
+
+        # Fetches the current scoped entity based on the scoping strategy.
+        #
+        # @return [ActiveRecord::Base, nil] the current scoped entity or nil if not found
+        # @raise [NotImplementedError] if the scoping strategy is unknown
+        def fetch_current_scoped_entity
+          case scoped_entity_strategy
           when :path
-            scoped_entity_class
-              .associated_with(current_user)
-              .from_path_param(request.path_parameters[scoped_entity_param_key])
-              .first! # Raise NotFound if user does not have access to the entity or it does not exist
+            fetch_entity_from_path
           when Symbol
-            send scoped_entity_strategy
+            send(scoped_entity_strategy)
           else
-            raise NotImplementedError, "unknown scoped entity strategy: #{scoped_entity_strategy.inspect}"
+            raise NotImplementedError, "Unknown scoped entity strategy: #{scoped_entity_strategy.inspect}"
           end
         end
 
+        # Fetches the scoped entity from the path parameters.
+        #
+        # @return [ActiveRecord::Base] the scoped entity
+        # @raise [ActiveRecord::RecordNotFound] if the entity is not found or the user doesn't have access
+        def fetch_entity_from_path
+          scoped_entity_class
+            .associated_with(current_user)
+            .from_path_param(request.path_parameters[scoped_entity_param_key])
+            .first!
+        end
+
+        # Remembers the current scoped entity in the session.
+        #
+        # @return [void]
         def remember_scoped_entity
           return unless scoped_to_entity?
 
           session[scoped_entity_session_key] = current_scoped_entity.to_global_id.to_s
         end
 
+        # Retrieves the remembered scoped entity from the session.
+        #
+        # @return [ActiveRecord::Base, nil] the remembered scoped entity or nil if not found
+        # @raise [NotImplementedError] if not scoped to an entity
         def remembered_scoped_entity
-          ensure_legal_entity_scoping_method_access! :remembered_scoped_entity
-
-          @remembered_scoped_entity ||= GlobalID::Locator.locate session[scoped_entity_session_key]
+          ensure_legal_entity_scoping_method_access!(__method__)
+          @remembered_scoped_entity ||= GlobalID::Locator.locate(session[scoped_entity_session_key])
         end
 
+        # Ensures that the method call is legal within the current scoping context.
+        #
+        # @param method [Symbol] the method being called
+        # @raise [NotImplementedError] if not scoped to an entity
         def ensure_legal_entity_scoping_method_access!(method)
           return if scoped_to_entity?
 
-          raise NotImplementedError, "this request is not scoped to an entity\n\n" \
-                                     "add the `scope_to_entity YourEntityRecord` directive in " \
-                                     "#{current_engine} or implement #{self.class}##{method}"
+          raise NotImplementedError, <<~ERROR_MESSAGE
+            This request is not scoped to an entity.
+
+            Add the `scope_to_entity YourEntityRecord` directive in #{current_engine}
+            or implement #{self.class}##{method}
+          ERROR_MESSAGE
         end
       end
     end

data/lib/plutonium/helpers/assets_helper.rb

@@ -1,41 +1,94 @@
+# frozen_string_literal: true
+
 module Plutonium
   module Helpers
+    # Helper module for managing asset-related functionality
     module AssetsHelper
+      # Generate a stylesheet tag for the resource
+      #
+      # @return [ActiveSupport::SafeBuffer] HTML stylesheet link tag
       def resource_stylesheet_tag
-        url = if Plutonium.development?
-          filename = JSON.parse(File.read(Plutonium.root.join("src", "build", "css.manifest")))["plutonium.css"]
-          "/build/#{filename}"
-        else
-          resource_stylesheet_asset
-        end
-        stylesheet_link_tag url, "data-turbo-track": "reload"
+        url = resource_asset_url_for(:css, resource_stylesheet_asset)
+        stylesheet_link_tag(url, "data-turbo-track": "reload")
       end
 
+      # Generate a script tag for the resource
+      #
+      # @return [ActiveSupport::SafeBuffer] HTML script tag
       def resource_script_tag
-        url = if Plutonium.development?
-          filename = JSON.parse(File.read(Plutonium.root.join("src", "build", "js.manifest")))["plutonium.js"]
-          "/build/#{filename}"
-        else
-          resource_script_asset
-        end
-        javascript_include_tag url, "data-turbo-track": "reload", type: "module"
+        url = resource_asset_url_for(:js, resource_script_asset)
+        javascript_include_tag(url, "data-turbo-track": "reload", type: "module")
       end
 
+      # Generate a favicon link tag
+      #
+      # @return [ActiveSupport::SafeBuffer] HTML favicon link tag
       def resource_favicon_tag
-        favicon_link_tag resource_favicon_asset
+        favicon_link_tag(resource_favicon_asset)
       end
 
+      # Generate an image tag for the logo
+      #
+      # @param classname [String] CSS class name for the image tag
+      # @return [ActiveSupport::SafeBuffer] HTML image tag
       def resource_logo_tag(classname:)
-        image_tag resource_logo_asset, class: classname
+        image_tag(resource_logo_asset, class: classname)
       end
 
-      def resource_logo_asset = Rails.application.config.plutonium.assets.logo
+      # Get the logo asset path
+      #
+      # @return [String] path to the logo asset
+      def resource_logo_asset
+        Plutonium.configuration.assets.logo
+      end
 
-      def resource_stylesheet_asset = Rails.application.config.plutonium.assets.stylesheet
+      # Get the stylesheet asset path
+      #
+      # @return [String] path to the stylesheet asset
+      def resource_stylesheet_asset
+        Plutonium.configuration.assets.stylesheet
+      end
 
-      def resource_script_asset = Rails.application.config.plutonium.assets.script
+      # Get the script asset path
+      #
+      # @return [String] path to the script asset
+      def resource_script_asset
+        Plutonium.configuration.assets.script
+      end
 
-      def resource_favicon_asset = Rails.application.config.plutonium.assets.favicon
+      # Get the favicon asset path
+      #
+      # @return [String] path to the favicon asset
+      def resource_favicon_asset
+        Plutonium.configuration.assets.favicon
+      end
+
+      private
+
+      # Generate the appropriate asset URL based on the environment
+      #
+      # @param type [Symbol] asset type (:css or :js)
+      # @param fallback [String] fallback asset path
+      # @return [String] asset URL
+      def resource_asset_url_for(type, fallback)
+        if Plutonium.configuration.development?
+          resource_development_asset_url(type)
+        else
+          fallback
+        end
+      end
+
+      # Generate the asset URL for development environment
+      #
+      # @param type [Symbol] asset type (:css or :js)
+      # @return [String] asset URL for development
+      def resource_development_asset_url(type)
+        manifest_file = (type == :css) ? "css.manifest" : "js.manifest"
+        asset_key = (type == :css) ? "plutonium.css" : "plutonium.js"
+
+        filename = JSON.parse(File.read(Plutonium.root.join("src", "build", manifest_file)))[asset_key]
+        "/build/#{filename}"
+      end
     end
   end
 end

data/lib/plutonium/pkg/app.rb

@@ -1,4 +1,4 @@
-require "active_support/notifications"
+# frozen_string_literal: true
 
 module Plutonium
   module Pkg
@@ -11,10 +11,11 @@ module Plutonium
       end
 
       class_methods do
+        include Plutonium::Concerns::ResourceValidatable
         attr_reader :scoped_entity_class, :scoped_entity_strategy, :scoped_entity_param_key
 
         def scope_to_entity(entity_class, strategy: :path, param_key: nil)
-          raise "#{entity_class} is not a valid resource record" unless entity_class.include?(Plutonium::Resource::Record)
+          validate_resource! entity_class
 
           @scoped_entity_class = entity_class
           @scoped_entity_strategy = strategy
@@ -25,122 +26,9 @@ module Plutonium
           scoped_entity_class.present?
         end
 
-        def initialize_register!
-          # this exists solely to support hot reloads
-          # if the user has modified the register especially if they removed a registration, we have no way of telling
-          # so instead we start over
-          @resource_register = []
-        end
-
-        def register_resource(resource)
-          @resource_register.append resource
-        end
-
-        def resource_register
-          @resource_register || []
-        end
-
-        def registered_resource_route_key_lookup
-          @registered_resource_route_key_lookup = resource_register.map { |resource|
-            [resource.model_name.singular_route_key.to_sym, resource]
-          }.to_h
-        end
-
-        def draw_custom_routes(&block)
-          @custom_routes_block = block
-        end
-
-        def draw_resource_routes
-          ActiveSupport::Notifications.instrument("plutonium.app.draw_resource_routes", app: self.class.module_parent.to_s) do
-            draw_resource_routes_internal
-          end
-        end
-
         def dom_id
           module_parent_name.underscore.dasherize
         end
-
-        private
-
-        def draw_resource_routes_internal
-          custom_routes_block = @custom_routes_block
-          registered_resources = resource_register
-          scoped_entity_param_key = self.scoped_entity_param_key if scoped_entity_strategy == :path
-          routes.draw do
-            shared_resource_concerns = [:interactive_resource_actions] # TODO: make this a config parameter
-            concern :interactive_resource_actions do
-              # these concerns power the interactive actions feature
-              member do
-                get "record_actions/:interactive_action", action: :begin_interactive_resource_record_action,
-                  as: :interactive_resource_record_action
-                post "record_actions/:interactive_action", action: :commit_interactive_resource_record_action
-              end
-
-              collection do
-                get "collection_actions/:interactive_action", action: :begin_interactive_resource_collection_action,
-                  as: :interactive_resource_collection_action
-                post "collection_actions/:interactive_action", action: :commit_interactive_resource_collection_action
-
-                get "recordless_actions/:interactive_action", action: :begin_interactive_resource_recordless_action,
-                  as: :interactive_resource_recordless_action
-                post "recordless_actions/:interactive_action", action: :commit_interactive_resource_recordless_action
-              end
-            end
-
-            resource_route_names = []
-            resource_route_opts_lookup = {}
-            # for each of our registered resources, we are registering the routes required
-            registered_resources.each do |resource|
-              resource_name = resource.to_s # Deeply::Namespaced::ResourceModel
-              resource_controller = resource_name.pluralize.underscore # deeply/namespaced/resource_models
-              resource_route = resource.model_name.plural # deeply_namespaced_resource_models
-              resource_route_name = :"#{resource_route}_routes" # deeply_namespaced_resource_models_routes
-
-              resource_route_opts = {}
-              # rails is not smart enough to infer Deeply::Namespaced::ResourceModelsController from deeply_namespaced_resource_models
-              # since we are heavy on namespaces, we choose to be explicit to guarantee there is no confusion
-              resource_route_opts[:controller] = resource_controller
-              # using collection for path is much nicer than the alternative
-              # e.g. deeply/namespaced/resource_models vs deeply_namespaced_resource_models
-              resource_route_opts[:path] = resource.model_name.collection
-              resource_route_opts_lookup[resource_route] = resource_route_opts
-
-              # defining our resources with concerns allows us to defer materializing till later,
-              # ensuring that resource_route_opts_lookup is populated
-              concern resource_route_name do
-                resources resource_route, **resource_route_opts, concerns: shared_resource_concerns do
-                  nested_resources_route_opts = resource_route_opts_lookup.slice(*resource.has_many_association_routes)
-                  nested_resources_route_opts.each do |nested_resource_route, nested_resource_route_opts|
-                    resources nested_resource_route, **nested_resource_route_opts, concerns: shared_resource_concerns
-                  end
-                end
-              end
-              resource_route_names << resource_route_name
-            end
-
-            # materialize our routes using a scope
-            # if the app is scoped to an entity, ensure that the expected route param and url helper prefix are specified.
-
-            # path   => /:entity/deeply/namespaced/resource_models/:deeply_namespaced_resource_model_id/
-            # helper => entity_deeply_namespaced_resource_models_path
-            scope_name = scoped_entity_param_key.present? ? ":#{scoped_entity_param_key}" : ""
-
-            # path   => /deeply/namespaced/resource_models/:deeply_namespaced_resource_model_id/
-            # helper => deeply_namespaced_resource_models_path
-            scope_options = scoped_entity_param_key.present? ? {as: scoped_entity_param_key} : {}
-
-            scope scope_name, scope_options do
-              instance_exec(&custom_routes_block) if custom_routes_block.present?
-              # we have to reverse sort our resource routes in order to prevent routing conflicts
-              # e.g. /blogs/1 and blogs/comments cause an issue if Blog is registered before Blogs::Comment
-              # attempting to load blogs/comments routes to blogs/:id which fails with a 404 since BlogsController
-              # essentially performs a Blog.find('comments')
-              # since the route names for these 2 will be 'blogs' and 'blog_comments',
-              # reverse sorting ensures that blog_comments is registered first, preventing the issue described above
-              concerns resource_route_names.sort
-            end
-          end
-        end
       end
     end
   end

data/lib/plutonium/pkg/concerns/resource_validatable.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Pkg
+    module Concerns
+      # Provides methods for validating Plutonium resources
+      module ResourceValidatable
+        extend ActiveSupport::Concern
+
+        # Custom error class for invalid resources
+        class InvalidResourceError < StandardError; end
+
+        private
+
+        # Validates if a given resource is a valid Plutonium::Resource::Record
+        #
+        # @param resource [Object] The resource to validate
+        # @raise [InvalidResourceError] If the resource is not valid
+        # @return [void]
+        def validate_resource!(resource)
+          unless valid_resource?(resource)
+            raise InvalidResourceError, "#{resource} is not a valid Plutonium::Resource::Record"
+          end
+        end
+
+        # Checks if a given resource is a valid Plutonium::Resource::Record
+        #
+        # @param resource [Object] The resource to check
+        # @return [Boolean] True if the resource is valid, false otherwise
+        def valid_resource?(resource)
+          resource.is_a?(Class) && resource.include?(Plutonium::Resource::Record)
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/railtie.rb

@@ -1,45 +1,76 @@
+# frozen_string_literal: true
+
 require "view_component"
 
 module Plutonium
+  # Plutonium::Railtie integrates Plutonium with Rails applications.
+  #
+  # This Railtie sets up configurations, initializers, and tasks for Plutonium
+  # to work seamlessly within a Rails environment.
   class Railtie < Rails::Railtie
-    config.plutonium = ActiveSupport::OrderedOptions.new
-    config.plutonium.cache_discovery = defined?(Rails.env) && !Rails.env.development?
-    config.plutonium.enable_hotreload = defined?(Rails.env) && Rails.env.development?
-
-    config.plutonium.assets = ActiveSupport::OrderedOptions.new
-    config.plutonium.assets.logo = "plutonium.png"
-    config.plutonium.assets.favicon = "plutonium.ico"
-    config.plutonium.assets.stylesheet = "plutonium.css"
-    config.plutonium.assets.script = "plutonium.min.js"
-
+    # Assets to be precompiled
+    #
     # If you don't want to precompile Plutonium's assets (eg. because you're using webpack),
     # you can do this in an intiailzer:
     #
     # config.after_initialize do
     #   config.assets.precompile -= Plutonium::Railtie::PRECOMPILE_ASSETS
     # end
-    PRECOMPILE_ASSETS = %w[plutonium.js plutonium.js.map plutonium.min.js plutonium.min.js.map plutonium.css plutonium.png plutonium.ico]
+    PRECOMPILE_ASSETS = %w[
+      plutonium.js plutonium.js.map plutonium.min.js plutonium.min.js.map
+      plutonium.css plutonium.png plutonium.ico
+    ].freeze
 
     initializer "plutonium.assets" do
-      next unless Rails.application.config.respond_to?(:assets)
+      setup_asset_pipeline if Rails.application.config.respond_to?(:assets)
+    end
+
+    initializer "plutonium.load_components" do
+      load_base_component
+    end
+
+    initializer "plutonium.initializers" do
+      load_plutonium_initializers
+    end
 
+    initializer "plutonium.asset_server" do
+      setup_development_asset_server if Plutonium.configuration.development?
+    end
+
+    initializer "plutonium.view_components_capture_compat" do
+      config.view_component.capture_compatibility_patch_enabled = true
+    end
+
+    initializer "plutonium.action_dispatch_extensions" do
+      extend_action_dispatch
+    end
+
+    rake_tasks do
+      load "tasks/create_rodauth_admin.rake"
+    end
+
+    config.after_initialize do
+      Plutonium::Reloader.start! if Plutonium.configuration.enable_hotreload
+      Plutonium::ZEITWERK_LOADER.eager_load if Rails.env.production?
+    end
+
+    private
+
+    def setup_asset_pipeline
       Rails.application.config.assets.precompile += PRECOMPILE_ASSETS
       Rails.application.config.assets.paths << Plutonium.root.join("app/assets").to_s
     end
 
-    initializer "plutonium.load_components" do
+    def load_base_component
       load Plutonium.root.join("app", "views", "components", "base.rb")
     end
 
-    initializer "plutonium.initializers" do
+    def load_plutonium_initializers
       Dir.glob(Plutonium.root.join("config", "initializers", "**", "*.rb")) { |file| load file }
     end
 
-    initializer "plutonium.asset_server" do
-      next unless Plutonium.development?
-
+    def setup_development_asset_server
       puts "=> [plutonium] starting assets server"
-      # setup a middleware to serve our assets
       config.app_middleware.insert_before(
         ActionDispatch::Static,
         Rack::Static,
@@ -47,23 +78,15 @@ module Plutonium
         root: Plutonium.root.join("src").to_s,
         cascade: true,
         header_rules: [
-          # Cache all static files in public caches (e.g. Rack::Cache) as well as in the browser
           [:all, {"cache-control" => "public, max-age=31536000"}]
         ]
       )
     end
 
-    initializer "plutonium.view_components_capture_compat" do
-      config.view_component.capture_compatibility_patch_enabled = true
-    end
-
-    rake_tasks do
-      load "tasks/create_rodauth_admin.rake"
-    end
-
-    config.after_initialize do
-      Plutonium::Reloader.start! if Rails.application.config.plutonium.enable_hotreload
-      Plutonium::ZEITWERK_LOADER.eager_load if Rails.env.production?
+    def extend_action_dispatch
+      ActionDispatch::Routing::Mapper.prepend Plutonium::Routing::MapperExtensions
+      ActionDispatch::Routing::RouteSet.prepend Plutonium::Routing::RouteSetExtensions
+      Rails::Engine.include Plutonium::Routing::ResourceRegistration
     end
   end
 end