redmine_plugin_kit 1.0.10 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 742a6b7ef926f76e6c7615961748e673590423a410041567a15743692337e753
4
- data.tar.gz: 2a63b5273c96b44f8c42f7f473a462acf2352979137331e61b3baca6fd835e1f
3
+ metadata.gz: 437f5cd3183cff072e1ef6e1481cdf2c1455cb9127a8827b06e925cf2fbed17c
4
+ data.tar.gz: aadde8474b6a811142c1d8fe0d9255c9995838418ec40cd308c207c947644142
5
5
  SHA512:
6
- metadata.gz: 3b339aad3aa4192aecc5b385678b656a93e1b3e820f0d7f20500f89c8bd35f81be1c2dd49c66e860721b75d4b856bd4058a7eced562941ee802df0738c48f967
7
- data.tar.gz: 4d11d3f39bcc013d6addd4cbc03ada64a13f51b0be1e5ca446f693f4a6e88e0c7431a67415078ee88df07d49336395a7986e04778ef513061f9da5e96355357c
6
+ metadata.gz: 8d185ff31399258570a19d4d129f66ae17698c3250740986a80fa285cfbfed4887042bfc2ddb6b1ae536544af037feb49a285bffb098493f3e4132bf3351bde7
7
+ data.tar.gz: 48fa844ac993789ac1b13e5a92f9e355d5b411875775880398c01ed1e880abd86a66e67654a233d1dfaf5700e917e10f8686e10b827bb3ae72dec1cd77bd8690
data/README.md CHANGED
@@ -10,6 +10,7 @@ If you are a Redmine developer, feel free and offer PRs with your Improvements.
10
10
 
11
11
  - Loader for plugin customizations
12
12
  - Deface support for Redmine plugins
13
+ - Extension points: classes a plugin collects from all plugins, without a list naming them
13
14
 
14
15
  ## Why this gem?
15
16
 
@@ -18,8 +19,8 @@ If you are a Redmine developer, feel free and offer PRs with your Improvements.
18
19
 
19
20
  ## Requirements
20
21
 
21
- - Redmine `>= 4.1.0` (including upcoming)
22
- - Ruby `>= 2.7` (only maintained ruby versions are supported)
22
+ - Redmine `>= 7.0` (including upcoming)
23
+ - Ruby `>= 3.2` (only maintained ruby versions are supported)
23
24
 
24
25
  ## Installation
25
26
 
@@ -28,3 +29,49 @@ Add Gem to your Gemfile:
28
29
  ```ruby
29
30
  gem 'redmine_plugin_kit'
30
31
  ```
32
+
33
+ ## Extension points
34
+
35
+ A plugin (the host) can collect classes from all plugins, one file per class, e.g. widgets of `my_host`:
36
+
37
+ - every plugin keeps its classes in `lib/widgets/`; the host also has the module `lib/widgets.rb`, which makes it the host
38
+ - 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.
39
+
40
+ ```ruby
41
+ loader = RedminePluginKit::Loader.new plugin_id: 'my_plugin'
42
+ loader.extends %w[widgets]
43
+
44
+ # a plugin without RedminePluginKit::Loader
45
+ RedminePluginKit::Extensions.declare __dir__, %w[widgets]
46
+ ```
47
+
48
+ `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.
49
+
50
+ 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:
51
+
52
+ ```ruby
53
+ assert_empty RedminePluginKit::Extensions.undeclared_dirs(plugin_dir, standalone: %w[searches])
54
+ ```
55
+
56
+ `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.
57
+
58
+ The host loads and lists them:
59
+
60
+ ```ruby
61
+ module Widgets
62
+ class Base
63
+ extend RedminePluginKit::Extensions::Abstract
64
+
65
+ abstract!
66
+ end
67
+ end
68
+
69
+ # in the setup of the host, which runs at boot and after every code reload
70
+ RedminePluginKit::Extensions.load! 'widgets'
71
+
72
+ # the loaded subclasses without abstract ones; with a key, a subclass with the
73
+ # same key replaces its superclass and two unrelated classes are an error
74
+ RedminePluginKit::Extensions.classes Widgets::Base, key: :widget_name
75
+ ```
76
+
77
+ A file name used by several plugins stops the boot, as Zeitwerk would load only one of them.
@@ -1,10 +1,14 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ # The plugin directory of Redmine, as Redmine::PluginLoader uses it: tests may
4
+ # point it elsewhere (REDMINE_PLUGINS_DIRECTORY), so not always plugins/
5
+ plugins_dir = Rails.root.join(Rails.application.config.try(:redmine_plugins_directory) || 'plugins')
6
+
3
7
  Rails.application.paths['app/overrides'] ||= []
4
- Rails.root.glob('plugins/*/app/overrides').each do |path|
8
+ plugins_dir.glob('*/app/overrides').each do |path|
5
9
  Rails.application.paths['app/overrides'] << path unless Rails.application.paths['app/overrides'].include? path
6
10
  end
7
11
 
8
- Rails.root.glob('plugins/*/app/overrides/**/*.deface').each do |path|
9
- Deface::DSL::Loader.load File.expand_path(path, __FILE__)
12
+ plugins_dir.glob('*/app/overrides/**/*.deface').each do |path|
13
+ Deface::DSL::Loader.load path.to_s
10
14
  end
@@ -0,0 +1,159 @@
1
+ # frozen_string_literal: true
2
+
3
+ module RedminePluginKit
4
+ # Classes one plugin (the host) collects from all plugins, a file per class
5
+ # and no list naming them, e.g. dashboard blocks:
6
+ #
7
+ # - every plugin keeps them in lib/<point>/; the host also has the module
8
+ # lib/<point>.rb, which makes it the host
9
+ # - any other plugin declares the point in its init.rb with
10
+ # loader.extends %w[<point>]. Zeitwerk then never eager loads its
11
+ # lib/<point>/, only load! of the host loads it, so without the host the
12
+ # files need no guard against a missing base class. They stay autoloadable
13
+ # though: nothing outside lib/<point>/ may refer to their constants, and
14
+ # defined?(<Point>) is no test for the host.
15
+ #
16
+ # The host loads them with load! and gets them with classes, which reads
17
+ # only what load! loaded: read them at runtime, not in the setup of a plugin,
18
+ # as the setups run in plugin order.
19
+ module Extensions
20
+ # Zeitwerk loads only one of two files of the same name in different
21
+ # plugins and drops the other one silently
22
+ class DuplicateError < StandardError; end
23
+
24
+ # Two classes with the same key, neither a subclass of the other
25
+ class ConflictError < StandardError; end
26
+
27
+ # A plugin has lib/<point>/ of another plugin without declaring it: without
28
+ # that plugin installed, its files would fail on the missing base class
29
+ class UndeclaredError < StandardError; end
30
+
31
+ # For the base classes of a point, which are no extension themselves
32
+ module Abstract
33
+ def abstract!
34
+ @abstract = true
35
+ end
36
+
37
+ # Not inherited: a subclass of a base class is an extension
38
+ def abstract?
39
+ @abstract == true
40
+ end
41
+ end
42
+
43
+ class << self
44
+ # Called from init.rb (see Loader#extends). Redmine runs it in
45
+ # to_prepare, after Zeitwerk is set up, so ignoring is too late there,
46
+ # but it runs before eager loading.
47
+ def declare(plugin_dir, points, loader: Rails.autoloaders.main, declared: declarations)
48
+ plugin_id = File.basename plugin_dir.to_s
49
+ points = Array(points).map(&:to_s)
50
+ declared[plugin_id] = declared.fetch(plugin_id, []) | points
51
+
52
+ points.each { |point| loader.do_not_eager_load File.join(plugin_dir.to_s, 'lib', point) }
53
+ end
54
+
55
+ # Points by plugin id
56
+ def declarations
57
+ @declarations ||= {}
58
+ end
59
+
60
+ # For a convention test of a plugin: directories in lib/ with classes but
61
+ # no module lib/<name>.rb, which are neither declared nor named as
62
+ # standalone. Unlike the check at boot, it needs no host installed.
63
+ def undeclared_dirs(plugin_dir, standalone: [], declared: declarations)
64
+ plugin_dir = plugin_dir.to_s
65
+ lib = File.join plugin_dir, 'lib'
66
+ candidates = File.directory?(lib) ? Dir.children(lib).select { |name| guest_dir? plugin_dir, name } : []
67
+ standalone = standalone.map(&:to_s)
68
+ points = declared.fetch File.basename(plugin_dir), []
69
+
70
+ # A stale entry would hide a directory added later under its name
71
+ check_standalone! standalone - candidates, 'names no directory with classes and without a module'
72
+ check_standalone! standalone & points, 'names a point declared with loader.extends'
73
+
74
+ (candidates - points - standalone).sort
75
+ end
76
+
77
+ # Loads the classes of all plugins; call it from the setup of the host,
78
+ # which runs at boot and after every code reload
79
+ # Declared directories are excluded from eager loading, so each file is
80
+ # loaded on its own (load_file honours no exclusion, unlike
81
+ # eager_load_dir, which would skip them silently).
82
+ def load!(point, plugin_dirs: redmine_plugin_dirs, loader: Rails.autoloaders.main, declared: declarations)
83
+ check_declared! point, plugin_dirs, declared
84
+ dirs = directories point, plugin_dirs: plugin_dirs
85
+ check_duplicates! dirs
86
+ dirs.each do |dir|
87
+ Dir.glob('**/*.rb', base: dir).each { |file| loader.load_file File.join(dir, file) }
88
+ end
89
+ loaded_points << point.to_s
90
+ end
91
+
92
+ # Whether load! ran for the point; until then classes would miss the
93
+ # extensions of all plugins
94
+ def loaded?(point)
95
+ loaded_points.include? point.to_s
96
+ end
97
+
98
+ # Runs from load!, after the init.rb of all plugins
99
+ def check_declared!(point, plugin_dirs, declared)
100
+ undeclared = plugin_dirs.select { |dir| guest_dir?(dir, point) && declared.fetch(File.basename(dir), []).exclude?(point) }
101
+ return if undeclared.empty?
102
+
103
+ raise UndeclaredError,
104
+ "lib/#{point} of #{undeclared.map { |dir| File.basename dir }.join ', '} is not declared, " \
105
+ "add to init.rb: loader.extends %w[#{point}]"
106
+ end
107
+
108
+ def directories(point, plugin_dirs: redmine_plugin_dirs)
109
+ candidates = plugin_dirs.map { |plugin_dir| File.join plugin_dir, 'lib', point }
110
+ candidates.select! { |dir| File.directory? dir }
111
+ candidates
112
+ end
113
+
114
+ # Directories of the same name are fine, Zeitwerk merges them
115
+ def check_duplicates!(dirs)
116
+ duplicates = dirs.flat_map { |dir| Dir.glob '**/*.rb', base: dir }.tally.select { |_file, count| count > 1 }.keys
117
+ raise DuplicateError, "In several plugins: #{duplicates.join ', '}" if duplicates.any?
118
+ end
119
+
120
+ # The loaded subclasses of a base, without base classes and anonymous
121
+ # classes (e.g. of tests). With a key (e.g. :block_id) classes with the
122
+ # same key are one extension: a subclass replaces its superclass, so a
123
+ # plugin can change an extension of another one.
124
+ def classes(base, key: nil)
125
+ found = base.descendants.reject { |klass| klass.abstract? || klass.name.nil? }
126
+ return found unless key
127
+
128
+ found.group_by(&key).map { |value, same_key| most_specific value, same_key }
129
+ end
130
+
131
+ private
132
+
133
+ def loaded_points
134
+ @loaded_points ||= Set.new
135
+ end
136
+
137
+ def check_standalone!(names, problem)
138
+ raise ArgumentError, "standalone #{problem}: #{names.join ', '}" if names.any?
139
+ end
140
+
141
+ # lib/<name>/ with classes, but without the module of a host
142
+ def guest_dir?(plugin_dir, name)
143
+ dir = File.join plugin_dir, 'lib', name
144
+ File.directory?(dir) && !File.file?("#{dir}.rb") && Dir.glob('**/*.rb', base: dir).any?
145
+ end
146
+
147
+ def most_specific(value, classes)
148
+ found = classes.detect { |candidate| classes.all? { |other| candidate <= other } }
149
+ raise ConflictError, "#{value}: #{classes.map(&:name).join ', '}" unless found
150
+
151
+ found
152
+ end
153
+
154
+ def redmine_plugin_dirs
155
+ Redmine::PluginLoader.directories.map(&:to_s)
156
+ end
157
+ end
158
+ end
159
+ end
@@ -11,7 +11,7 @@ module RedminePluginKit
11
11
  link_to name, link, **options
12
12
  end
13
13
 
14
- def link_to_url(url, **options)
14
+ def link_to_url(url, **)
15
15
  return if url.blank?
16
16
 
17
17
  parts = url.split '://'
@@ -22,7 +22,7 @@ module RedminePluginKit
22
22
  url.chomp '/'
23
23
  end
24
24
 
25
- link_to_external name, url, **options
25
+ link_to_external(name, url, **)
26
26
  end
27
27
  end
28
28
  end
@@ -21,8 +21,8 @@ module RedminePluginKit
21
21
  yield
22
22
  end
23
23
 
24
- def after_initialize(&block)
25
- Rails.application.config.after_initialize(&block)
24
+ def after_initialize(&)
25
+ Rails.application.config.after_initialize(&)
26
26
  end
27
27
 
28
28
  # required multiple times because of this bug: https://www.redmine.org/issues/33290
@@ -40,6 +40,53 @@ module RedminePluginKit
40
40
  Gem.loaded_specs[plugin_id].full_gem_path
41
41
  end
42
42
  end
43
+
44
+ # The files to load again after a code reload, in the order of their
45
+ # registration, each with the number of code reloads it was last loaded
46
+ # at. Kept on the class: the setup of a plugin runs at boot and after
47
+ # every code reload and registers its files each time.
48
+ def reloadable_files
49
+ @reloadable_files ||= {}
50
+ end
51
+
52
+ def reload_on_prepare(file)
53
+ watch_code_reloads
54
+ # the require of the caller loads the file for this number of reloads
55
+ reloadable_files[file] ||= code_reloads
56
+ end
57
+
58
+ private
59
+
60
+ def code_reloads
61
+ @code_reloads ||= 0
62
+ end
63
+
64
+ # One callback pair for all files, however often a file is registered
65
+ def watch_code_reloads
66
+ return if @watch_code_reloads
67
+
68
+ @watch_code_reloads = true
69
+ # the callbacks run in the context of the reloader
70
+ loader = self
71
+ ActiveSupport::Reloader.after_class_unload { loader.send :code_reloaded }
72
+ ActiveSupport::Reloader.to_prepare { loader.send :load_unloaded_files }
73
+ end
74
+
75
+ def code_reloaded
76
+ @code_reloads = code_reloads + 1
77
+ end
78
+
79
+ # Prepare also runs without a code reload: at boot, and in production and
80
+ # test, where code is never unloaded. The class of a file is still there
81
+ # then, and loading the file again would define its constants twice.
82
+ def load_unloaded_files
83
+ reloadable_files.each do |file, loaded_at|
84
+ next if loaded_at == code_reloads
85
+
86
+ load file
87
+ reloadable_files[file] = code_reloads
88
+ end
89
+ end
43
90
  end
44
91
 
45
92
  def initialize(plugin_id:, debug: false)
@@ -49,6 +96,12 @@ module RedminePluginKit
49
96
  apply_reset
50
97
  end
51
98
 
99
+ # lib/<point>/ of this plugin holds classes another plugin collects, see
100
+ # Extensions. Call it in init.rb.
101
+ def extends(points)
102
+ Extensions.declare plugin_dir, points
103
+ end
104
+
52
105
  def default_settings
53
106
  cached_settings_name = "@default_settings_#{plugin_id}"
54
107
  cached_settings = instance_variable_get cached_settings_name
@@ -85,7 +138,7 @@ module RedminePluginKit
85
138
  File.join plugin_dir, 'lib', plugin_id, spec
86
139
  end
87
140
 
88
- files = Dir[dir].sort
141
+ files = Dir[dir]
89
142
 
90
143
  files.reverse! if reverse
91
144
  files.each do |f|
@@ -98,9 +151,7 @@ module RedminePluginKit
98
151
  # plain text field showing the raw id. Reloading the file restores it.
99
152
  #
100
153
  # NOTE: the require below stays as it is, so booting behaves exactly as
101
- # before and does not depend on when to_prepare runs. Loading the file
102
- # again in the first prepare run is harmless: these files only define a
103
- # class and register it under a fixed name.
154
+ # before and does not depend on when to_prepare runs.
104
155
  reload_on_prepare f
105
156
  end
106
157
 
@@ -108,14 +159,12 @@ module RedminePluginKit
108
159
  end
109
160
  end
110
161
 
111
- # Load the file again after every code reload.
162
+ # Load the file again in the prepare run after every code reload.
112
163
  #
113
- # The block keeps the order of the surrounding loop, which matters because
164
+ # The files keep the order of the surrounding loop, which matters because
114
165
  # formats may inherit from each other (CompanyFormat < ContactFormat) - a
115
166
  # subclass loaded before its parent raises NameError.
116
- def reload_on_prepare(file)
117
- ActiveSupport::Reloader.to_prepare { load file }
118
- end
167
+ delegate :reload_on_prepare, to: :class
119
168
 
120
169
  def incompatible?(plugins = [])
121
170
  plugins.each do |plugin|
@@ -48,10 +48,9 @@ module RedminePluginKit
48
48
  # requires_redmine_plugin runs while init.rb is loaded (during alphabetical
49
49
  # registration) and therefore only works for dependencies that load earlier,
50
50
  # such as additionals / additional_tags. A dependency that loads later (e.g.
51
- # redmine_automation depending on redmine_reporting) would raise
51
+ # plugin_a depending on plugin_b) would raise
52
52
  # PluginNotFound even though it is installed. To see a plugin's hard
53
53
  # AlphaNodes dependencies, look at its REQUIRED_ALPHANODES_PLUGINS constant.
54
- # rubocop: disable Style/RaiseArgs
55
54
  def setup_required_plugins
56
55
  return unless defined? self::REQUIRED_ALPHANODES_PLUGINS
57
56
  raise 'VERSION missing for REQUIRED_ALPHANODES_PLUGINS' unless defined? self::VERSION
@@ -59,15 +58,14 @@ module RedminePluginKit
59
58
  self::REQUIRED_ALPHANODES_PLUGINS.each do |required_plugin|
60
59
  plugin = Redmine::Plugin.find required_plugin
61
60
  unless self::VERSION.include? plugin.version
62
- raise Redmine::PluginRequirementError.new "#{plugin_id} plugin requires #{required_plugin} plugin version #{self::VERSION}"
61
+ raise Redmine::PluginRequirementError, "#{plugin_id} plugin requires #{required_plugin} plugin version #{self::VERSION}"
63
62
  end
64
63
  rescue Redmine::PluginNotFound
65
- raise Redmine::PluginRequirementError.new "#{plugin_id} plugin requires the #{required_plugin} plugin." \
66
- "Please install #{required_plugin} plugin (https://alphanodes.com/#{required_plugin.tr '-',
67
- '_'})"
64
+ raise Redmine::PluginRequirementError,
65
+ "#{plugin_id} plugin requires the #{required_plugin} plugin. " \
66
+ "Please install #{required_plugin} plugin (https://alphanodes.com/#{required_plugin.tr '-', '_'})"
68
67
  end
69
68
  end
70
- # rubocop: enable Style/RaiseArgs
71
69
 
72
70
  def init_loader(existing_loader)
73
71
  @loader = existing_loader
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module RedminePluginKit
4
- VERSION = '1.0.10'
4
+ VERSION = '1.1.1'
5
5
  end
@@ -4,6 +4,7 @@ require 'deface'
4
4
 
5
5
  require 'redmine_plugin_kit/version'
6
6
  require 'redmine_plugin_kit/debug'
7
+ require 'redmine_plugin_kit/extensions'
7
8
  require 'redmine_plugin_kit/engine'
8
9
  require 'redmine_plugin_kit/plugin_base'
9
10
  require 'redmine_plugin_kit/loader'
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: redmine_plugin_kit
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.0.10
4
+ version: 1.1.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - AlphaNodes
@@ -50,12 +50,12 @@ files:
50
50
  - lib/redmine_plugin_kit.rb
51
51
  - lib/redmine_plugin_kit/debug.rb
52
52
  - lib/redmine_plugin_kit/engine.rb
53
+ - lib/redmine_plugin_kit/extensions.rb
53
54
  - lib/redmine_plugin_kit/helpers/global_helper.rb
54
55
  - lib/redmine_plugin_kit/loader.rb
55
56
  - lib/redmine_plugin_kit/plugin_base.rb
56
57
  - lib/redmine_plugin_kit/version.rb
57
58
  - lib/tasks/redmine_plugin_kit.rake
58
- - redmine_plugin_kit-1.0.9.gem
59
59
  homepage: https://github.com/alphanodes/redmine_plugin_kit
60
60
  licenses:
61
61
  - GPL-2.0
@@ -68,14 +68,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
68
68
  requirements:
69
69
  - - ">="
70
70
  - !ruby/object:Gem::Version
71
- version: '2.7'
71
+ version: 3.2.0
72
72
  required_rubygems_version: !ruby/object:Gem::Requirement
73
73
  requirements:
74
74
  - - ">="
75
75
  - !ruby/object:Gem::Version
76
76
  version: '0'
77
77
  requirements: []
78
- rubygems_version: 3.6.9
78
+ rubygems_version: 4.0.20
79
79
  specification_version: 4
80
80
  summary: Redmine plugin kit
81
81
  test_files: []
Binary file