redmine_plugin_kit 1.0.9 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94857a34d940b2fccba2f613e3299cef59acc88c20c3279671831fd923c3e28e
-  data.tar.gz: 4d6e9c22ea18b5050b9084fe60b577a4cb3da032801a13a0b16f6ec99664a443
+  metadata.gz: df099201258470b440ad75ae0fb6631ebcee98e347346b01be981a13fa26c0af
+  data.tar.gz: db29596ff3a4029ff11871fce14b8c4c0f6d8f5ab930762802854ac798bdc3d3
 SHA512:
-  metadata.gz: 90fe0d769fa01295f8dea757cff3aa5f9dc48005c8ee4ea356b6cdece1da7e0330f11020359cee3f9cb53c587eaa95281c7b7d1493d4a95be8cad1e7dbe26ad9
-  data.tar.gz: f3d7a85ab307ffe4425229878f41581e03a04a833e34f626e8336ae52005e6f2a04be166517d6fcdb6b32489ceda1d08ba2d58ebef77f3265547c71a9ebf605f
+  metadata.gz: 8bb91988a44e45448e2baa3e8c920780bbd6a6ffd27e7a2dce4d3d73e81d296d54fe5f54761a3a4924337e5d8cde99d2f73782c9162f70811a7e17f0a77e16f0
+  data.tar.gz: ba3c2b788544d8fc3363632b6414d9885f147ae6ae641eb94c47fd3a415291725f857e0171557a6143b49e84df4014fa86493166f175c3186dd4a94d46ea55da

data/README.md

@@ -10,6 +10,7 @@ If you are a Redmine developer, feel free and offer PRs with your Improvements.
 
 - Loader for plugin customizations
 - Deface support for Redmine plugins
+- Extension points: classes a plugin collects from all plugins, without a list naming them
 
 ## Why this gem?
 
@@ -19,7 +20,7 @@ If you are a Redmine developer, feel free and offer PRs with your Improvements.
 ## Requirements
 
 - Redmine `>= 4.1.0` (including upcoming)
-- Ruby `>= 2.7` (only maintained ruby versions are supported)
+- Ruby `>= 3.2` (only maintained ruby versions are supported)
 
 ## Installation
 
@@ -28,3 +29,49 @@ Add Gem to your Gemfile:
 ```ruby
 gem 'redmine_plugin_kit'
 ```
+
+## Extension points
+
+A plugin (the host) can collect classes from all plugins, one file per class, e.g. widgets of `my_host`:
+
+- every plugin keeps its classes in `lib/widgets/`; the host also has the module `lib/widgets.rb`, which makes it the host
+- any other plugin declares the point in its `init.rb`. Zeitwerk then never eager loads its `lib/widgets/`, only `load!` of the host loads it, so without the host these files need no guard against a missing base class. They stay autoloadable: nothing outside `lib/widgets/` may refer to their constants, and `defined?(Widgets)` is no test for the host.
+
+```ruby
+loader = RedminePluginKit::Loader.new plugin_id: 'my_plugin'
+loader.extends %w[widgets]
+
+# a plugin without RedminePluginKit::Loader
+RedminePluginKit::Extensions.declare __dir__, %w[widgets]
+```
+
+`classes` returns only what `load!` loaded, so read them at runtime, not in the setup of a plugin (the setups run in plugin order); `RedminePluginKit::Extensions.loaded? 'widgets'` tells whether `load!` ran.
+
+An undeclared `lib/widgets/` stops the boot as long as the host is installed. Without it, a convention test of the plugin finds such a directory:
+
+```ruby
+assert_empty RedminePluginKit::Extensions.undeclared_dirs(plugin_dir, standalone: %w[searches])
+```
+
+`standalone` names the directories in `lib/` with classes but no module that belong to the plugin itself; a name without such a directory is an error.
+
+The host loads and lists them:
+
+```ruby
+module Widgets
+  class Base
+    extend RedminePluginKit::Extensions::Abstract
+
+    abstract!
+  end
+end
+
+# in the setup of the host, which runs at boot and after every code reload
+RedminePluginKit::Extensions.load! 'widgets'
+
+# the loaded subclasses without abstract ones; with a key, a subclass with the
+# same key replaces its superclass and two unrelated classes are an error
+RedminePluginKit::Extensions.classes Widgets::Base, key: :widget_name
+```
+
+A file name used by several plugins stops the boot, as Zeitwerk would load only one of them.

data/lib/redmine_plugin_kit/extensions.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module RedminePluginKit
+  # Classes one plugin (the host) collects from all plugins, a file per class
+  # and no list naming them, e.g. dashboard blocks:
+  #
+  # - every plugin keeps them in lib/<point>/; the host also has the module
+  #   lib/<point>.rb, which makes it the host
+  # - any other plugin declares the point in its init.rb with
+  #   loader.extends %w[<point>]. Zeitwerk then never eager loads its
+  #   lib/<point>/, only load! of the host loads it, so without the host the
+  #   files need no guard against a missing base class. They stay autoloadable
+  #   though: nothing outside lib/<point>/ may refer to their constants, and
+  #   defined?(<Point>) is no test for the host.
+  #
+  # The host loads them with load! and gets them with classes, which reads
+  # only what load! loaded: read them at runtime, not in the setup of a plugin,
+  # as the setups run in plugin order.
+  module Extensions
+    # Zeitwerk loads only one of two files of the same name in different
+    # plugins and drops the other one silently
+    class DuplicateError < StandardError; end
+
+    # Two classes with the same key, neither a subclass of the other
+    class ConflictError < StandardError; end
+
+    # A plugin has lib/<point>/ of another plugin without declaring it: without
+    # that plugin installed, its files would fail on the missing base class
+    class UndeclaredError < StandardError; end
+
+    # For the base classes of a point, which are no extension themselves
+    module Abstract
+      def abstract!
+        @abstract = true
+      end
+
+      # Not inherited: a subclass of a base class is an extension
+      def abstract?
+        @abstract == true
+      end
+    end
+
+    class << self
+      # Called from init.rb (see Loader#extends). Redmine runs it in
+      # to_prepare, after Zeitwerk is set up, so ignoring is too late there,
+      # but it runs before eager loading.
+      def declare(plugin_dir, points, loader: Rails.autoloaders.main, declared: declarations)
+        plugin_id = File.basename plugin_dir.to_s
+        points = Array(points).map(&:to_s)
+        declared[plugin_id] = declared.fetch(plugin_id, []) | points
+
+        points.each { |point| loader.do_not_eager_load File.join(plugin_dir.to_s, 'lib', point) }
+      end
+
+      # Points by plugin id
+      def declarations
+        @declarations ||= {}
+      end
+
+      # For a convention test of a plugin: directories in lib/ with classes but
+      # no module lib/<name>.rb, which are neither declared nor named as
+      # standalone. Unlike the check at boot, it needs no host installed.
+      def undeclared_dirs(plugin_dir, standalone: [], declared: declarations)
+        plugin_dir = plugin_dir.to_s
+        lib = File.join plugin_dir, 'lib'
+        candidates = File.directory?(lib) ? Dir.children(lib).select { |name| guest_dir? plugin_dir, name } : []
+        standalone = standalone.map(&:to_s)
+        points = declared.fetch File.basename(plugin_dir), []
+
+        # A stale entry would hide a directory added later under its name
+        check_standalone! standalone - candidates, 'names no directory with classes and without a module'
+        check_standalone! standalone & points, 'names a point declared with loader.extends'
+
+        (candidates - points - standalone).sort
+      end
+
+      # Loads the classes of all plugins; call it from the setup of the host,
+      # which runs at boot and after every code reload
+      # Declared directories are excluded from eager loading, so each file is
+      # loaded on its own (load_file honours no exclusion, unlike
+      # eager_load_dir, which would skip them silently).
+      def load!(point, plugin_dirs: redmine_plugin_dirs, loader: Rails.autoloaders.main, declared: declarations)
+        check_declared! point, plugin_dirs, declared
+        dirs = directories point, plugin_dirs: plugin_dirs
+        check_duplicates! dirs
+        dirs.each do |dir|
+          Dir.glob('**/*.rb', base: dir).each { |file| loader.load_file File.join(dir, file) }
+        end
+        loaded_points << point.to_s
+      end
+
+      # Whether load! ran for the point; until then classes would miss the
+      # extensions of all plugins
+      def loaded?(point)
+        loaded_points.include? point.to_s
+      end
+
+      # Runs from load!, after the init.rb of all plugins
+      def check_declared!(point, plugin_dirs, declared)
+        undeclared = plugin_dirs.select { |dir| guest_dir?(dir, point) && declared.fetch(File.basename(dir), []).exclude?(point) }
+        return if undeclared.empty?
+
+        raise UndeclaredError,
+              "lib/#{point} of #{undeclared.map { |dir| File.basename dir }.join ', '} is not declared, " \
+              "add to init.rb: loader.extends %w[#{point}]"
+      end
+
+      def directories(point, plugin_dirs: redmine_plugin_dirs)
+        candidates = plugin_dirs.map { |plugin_dir| File.join plugin_dir, 'lib', point }
+        candidates.select! { |dir| File.directory? dir }
+        candidates
+      end
+
+      # Directories of the same name are fine, Zeitwerk merges them
+      def check_duplicates!(dirs)
+        duplicates = dirs.flat_map { |dir| Dir.glob '**/*.rb', base: dir }.tally.select { |_file, count| count > 1 }.keys
+        raise DuplicateError, "In several plugins: #{duplicates.join ', '}" if duplicates.any?
+      end
+
+      # The loaded subclasses of a base, without base classes and anonymous
+      # classes (e.g. of tests). With a key (e.g. :block_id) classes with the
+      # same key are one extension: a subclass replaces its superclass, so a
+      # plugin can change an extension of another one.
+      def classes(base, key: nil)
+        found = base.descendants.reject { |klass| klass.abstract? || klass.name.nil? }
+        return found unless key
+
+        found.group_by(&key).map { |value, same_key| most_specific value, same_key }
+      end
+
+      private
+
+      def loaded_points
+        @loaded_points ||= Set.new
+      end
+
+      def check_standalone!(names, problem)
+        raise ArgumentError, "standalone #{problem}: #{names.join ', '}" if names.any?
+      end
+
+      # lib/<name>/ with classes, but without the module of a host
+      def guest_dir?(plugin_dir, name)
+        dir = File.join plugin_dir, 'lib', name
+        File.directory?(dir) && !File.file?("#{dir}.rb") && Dir.glob('**/*.rb', base: dir).any?
+      end
+
+      def most_specific(value, classes)
+        found = classes.detect { |candidate| classes.all? { |other| candidate <= other } }
+        raise ConflictError, "#{value}: #{classes.map(&:name).join ', '}" unless found
+
+        found
+      end
+
+      def redmine_plugin_dirs
+        Redmine::PluginLoader.directories.map(&:to_s)
+      end
+    end
+  end
+end

data/lib/redmine_plugin_kit/helpers/global_helper.rb

@@ -11,7 +11,7 @@ module RedminePluginKit
         link_to name, link, **options
       end
 
-      def link_to_url(url, **options)
+      def link_to_url(url, **)
         return if url.blank?
 
         parts = url.split '://'
@@ -22,7 +22,7 @@ module RedminePluginKit
                  url.chomp '/'
                end
 
-        link_to_external name, url, **options
+        link_to_external(name, url, **)
       end
     end
   end

data/lib/redmine_plugin_kit/loader.rb

@@ -21,8 +21,8 @@ module RedminePluginKit
         yield
       end
 
-      def after_initialize(&block)
-        Rails.application.config.after_initialize(&block)
+      def after_initialize(&)
+        Rails.application.config.after_initialize(&)
       end
 
       # required multiple times because of this bug: https://www.redmine.org/issues/33290
@@ -49,6 +49,12 @@ module RedminePluginKit
       apply_reset
     end
 
+    # lib/<point>/ of this plugin holds classes another plugin collects, see
+    # Extensions. Call it in init.rb.
+    def extends(points)
+      Extensions.declare plugin_dir, points
+    end
+
     def default_settings
       cached_settings_name = "@default_settings_#{plugin_id}"
       cached_settings = instance_variable_get cached_settings_name
@@ -85,7 +91,7 @@ module RedminePluginKit
               File.join plugin_dir, 'lib', plugin_id, spec
             end
 
-      files = Dir[dir].sort
+      files = Dir[dir]
 
       files.reverse! if reverse
       files.each do |f|

data/lib/redmine_plugin_kit/plugin_base.rb

@@ -48,10 +48,9 @@ module RedminePluginKit
       # requires_redmine_plugin runs while init.rb is loaded (during alphabetical
       # registration) and therefore only works for dependencies that load earlier,
       # such as additionals / additional_tags. A dependency that loads later (e.g.
-      # redmine_automation depending on redmine_reporting) would raise
+      # plugin_a depending on plugin_b) would raise
       # PluginNotFound even though it is installed. To see a plugin's hard
       # AlphaNodes dependencies, look at its REQUIRED_ALPHANODES_PLUGINS constant.
-      # rubocop: disable Style/RaiseArgs
       def setup_required_plugins
         return unless defined? self::REQUIRED_ALPHANODES_PLUGINS
         raise 'VERSION missing for REQUIRED_ALPHANODES_PLUGINS' unless defined? self::VERSION
@@ -59,15 +58,14 @@ module RedminePluginKit
         self::REQUIRED_ALPHANODES_PLUGINS.each do |required_plugin|
           plugin = Redmine::Plugin.find required_plugin
           unless self::VERSION.include? plugin.version
-            raise Redmine::PluginRequirementError.new "#{plugin_id} plugin requires #{required_plugin} plugin version #{self::VERSION}"
+            raise Redmine::PluginRequirementError, "#{plugin_id} plugin requires #{required_plugin} plugin version #{self::VERSION}"
           end
         rescue Redmine::PluginNotFound
-          raise Redmine::PluginRequirementError.new "#{plugin_id} plugin requires the #{required_plugin} plugin." \
-                                              "Please install #{required_plugin} plugin (https://alphanodes.com/#{required_plugin.tr '-',
-                                                                                                                                     '_'})"
+          raise Redmine::PluginRequirementError,
+                "#{plugin_id} plugin requires the #{required_plugin} plugin. " \
+                "Please install #{required_plugin} plugin (https://alphanodes.com/#{required_plugin.tr '-', '_'})"
         end
       end
-      # rubocop: enable Style/RaiseArgs
 
       def init_loader(existing_loader)
         @loader = existing_loader

data/lib/redmine_plugin_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RedminePluginKit
-  VERSION = '1.0.9'
+  VERSION = '1.1.0'
 end

data/lib/redmine_plugin_kit.rb

@@ -4,6 +4,7 @@ require 'deface'
 
 require 'redmine_plugin_kit/version'
 require 'redmine_plugin_kit/debug'
+require 'redmine_plugin_kit/extensions'
 require 'redmine_plugin_kit/engine'
 require 'redmine_plugin_kit/plugin_base'
 require 'redmine_plugin_kit/loader'
@@ -26,6 +27,17 @@ module RedminePluginKit
       !true?(value)
     end
 
+    # Returns plugin settings with indifferent access and the given setting applied.
+    # Redmine stores plugin settings from the settings form this way, too. Without it,
+    # a string key from the command line would be added next to an existing symbol key,
+    # and plugins reading the symbol key would never see the new value.
+    def plugin_settings_with(settings, setting, value)
+      settings = {} unless settings.is_a? Hash
+      settings = settings.with_indifferent_access
+      settings[setting] = value
+      settings
+    end
+
     def textarea_cols(text, min: 8, max: 20)
       [[min, text.to_s.length / 50].max, max].min # rubocop: disable Style/ComparableClamp
     end

data/lib/tasks/redmine_plugin_kit.rake

@@ -46,9 +46,7 @@ namespace :redmine_plugin_kit do
       Setting[setting.to_sym] = value
     else
       plugin_name = :"plugin_#{name}"
-      plugin_settings = Setting[plugin_name]
-      plugin_settings[setting] = value
-      Setting[plugin_name] = plugin_settings
+      Setting[plugin_name] = RedminePluginKit.plugin_settings_with Setting[plugin_name], setting, value
     end
   end
 
@@ -76,7 +74,7 @@ namespace :redmine_plugin_kit do
     else
       plugin_name = :"plugin_#{name}"
       plugin_settings = Setting[plugin_name]
-      puts plugin_settings[setting]
+      puts plugin_settings.with_indifferent_access[setting] if plugin_settings.is_a? Hash
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redmine_plugin_kit
 version: !ruby/object:Gem::Version
-  version: 1.0.9
+  version: 1.1.0
 platform: ruby
 authors:
 - AlphaNodes
@@ -50,6 +50,7 @@ files:
 - lib/redmine_plugin_kit.rb
 - lib/redmine_plugin_kit/debug.rb
 - lib/redmine_plugin_kit/engine.rb
+- lib/redmine_plugin_kit/extensions.rb
 - lib/redmine_plugin_kit/helpers/global_helper.rb
 - lib/redmine_plugin_kit/loader.rb
 - lib/redmine_plugin_kit/plugin_base.rb
@@ -67,7 +68,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="