docscribe 1.3.3 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 755d272674fe454b80cc008acb50a879da920def321442cdc8cdd7c450b91f52
-  data.tar.gz: 92aa2320a36162272acfa2b430bfa9cccf5a4582770885a996bc61d7a4198bb6
+  metadata.gz: 50c74b921731749cbf32726e24e557e526e1f65966e704171a652d10cc4ce945
+  data.tar.gz: 2e254911cf9d81f5d5f7b5df29576c3c5c3c3f0433cfb387c0d22c1ce30eeb60
 SHA512:
-  metadata.gz: 9268725904b6644b4d46a89c72cda271c4d1b5fedc5066396af1515fa955fecb864fad10406db81582391f81d5265595c7c2bb6fe5793bfc1c7b465395937577
-  data.tar.gz: e8012b3c09ec75e8bd7bbed32f51b297edb2d081b65b2bdf849667e1c7cdb5469862697ddc060c8194b4bf08cc671cb61b6b94507ca382841745e27923963513
+  metadata.gz: 824133cf33505568edc84fe99bd51ced4451616552b2ba33e5584fcbd68bdd2ede0e4df365510a4e6be73ef9bf191a66e37746a5331e2ccb8abae2a80a3f69b4
+  data.tar.gz: 6662f828e5d324c226432df0e00359a36a97cd47dfeedefd4ead014752fbebe51b93e6cb693d6a342ca3d7e24683b74c189576792e558bf12e28bcc6365e2ed2

data/README.md

@@ -900,8 +900,9 @@ class DefineMethodPlugin < Docscribe::Plugin::Base::CollectorPlugin
   end
 end
 
-Docscribe::Plugin::Registry.register(SincePlugin.new)
-Docscribe::Plugin::Registry.register(DefineMethodPlugin.new)
+# You can optionally set priority (default: 0). Higher number => higher priority.
+Docscribe::Plugin::Registry.register(SincePlugin.new, priority: 10)
+Docscribe::Plugin::Registry.register(DefineMethodPlugin.new, priority: 0)
 ```
 
 **`docscribe.yml`**:
@@ -924,12 +925,34 @@ Docscribe::Plugin::Registry.register(
 )
 ```
 
+### Plugin priority
+
+`Registry.register(plugin, priority: N)` accepts an optional integer priority (default: `0`).
+Higher number means higher priority.
+
+**CollectorPlugin priority (conflicts at the same source position):**
+
+- If a plugin insertion and a standard *method* insertion share the same source position (
+  `anchor_node.loc.expression.begin_pos`), the standard insertion is dropped and the plugin insertion is kept.
+- If multiple CollectorPlugins insert at the same source position, only insertions from the highest-priority plugin(s)
+  are kept (ties are kept).
+- Multiple insertions from the winning plugin(s) at the same position are preserved (e.g. one `@!attribute` per column).
+
+**TagPlugin priority:**
+
+- TagPlugins run in descending priority order (higher priority runs earlier).
+- Multiple TagPlugins may emit the same tag name (e.g. two `@since` tags) — duplicates in the same run are allowed.
+
+This allows plugins like `ModelAttributes` to supply more accurate `@return`
+types for ActiveRecord model methods, replacing the generic docs the standard
+collector would have produced for the same `def`.
+
 ### Idempotency
 
 Docscribe handles idempotency for plugins automatically.
 
-**TagPlugin**: before appending a tag, Docscribe checks whether a tag with that name already exists in the current doc
-block. If it does, the tag is skipped.
+**TagPlugin**: in safe merge mode, Docscribe will not add a plugin tag if the existing doc block already contains a tag
+with that name. (Multiple TagPlugins can still emit the same tag name in a single run; duplicates are allowed.)
 
 **CollectorPlugin**: idempotency depends on the selected strategy.
 
@@ -943,7 +966,17 @@ on aggressive runs.
 
 ### Plugin examples
 
-Sample plugin available at [examples](examples/plugins) 
+Sample plugins available at [examples](examples/plugins):
+
+- **`ApiTagPlugin`** (`tag_plugin/`): TagPlugin that appends `@api public` / `@api private`
+  based on method visibility.
+- **`RailsAssociations`** (`collector_plugin/rails_associations/`): CollectorPlugin
+  that documents ActiveRecord `belongs_to`, `has_many`, etc.
+- **`SchemaAttributes`** (`collector_plugin/schema_attributes/`): CollectorPlugin
+  that generates `@!attribute` blocks by reading `db/schema.rb`.
+- **`ModelAttributes`** (`collector_plugin/model_attributes/`): CollectorPlugin
+  that generates accurate `@return` types for model methods using `db/schema.rb`
+  or `db/structure.sql`.
 
 ## Configuration
 

data/lib/docscribe/inline_rewriter.rb

@@ -102,6 +102,7 @@ module Docscribe
         all = method_insertions.map { |i| [:method, i] } +
               attr_insertions.map { |i| [:attr, i] } +
               plugin_insertions.map { |i| [:plugin, i] }
+        all = deduplicate_insertions(all)
         rewriter = Parser::Source::TreeRewriter.new(buffer)
         merge_inserts = Hash.new { |h, k| h[k] = [] }
         changes = []
@@ -148,6 +149,110 @@ module Docscribe
 
       private
 
+      # Deduplicate insertions by source position.
+      #
+      # Rules:
+      # 1. Plugin insertions override method insertions at the same position
+      #    (CollectorPlugin knows more than the standard collector for that node).
+      # 2. If multiple CollectorPlugins target the same position, only insertions
+      # from the highest priority plugin(s) are kept (ties are kept).
+      # 3. Multiple plugin insertions at the same position are allowed
+      # (a single plugin may generate multiple doc blocks, e.g. one per column).
+      #
+      # @private
+      # @param [Array<Array(Symbol,Object)>] insertions tagged insertion list
+      # @return [Array<Array(Symbol,Object)>]
+      def deduplicate_insertions(insertions)
+        groups = {}
+
+        insertions.each do |item|
+          kind, ins = item
+          pos = plugin_insertion_pos(kind, ins)
+          (groups[pos] ||= []) << item
+        end
+
+        result = []
+
+        groups.each do |pos, items|
+          plugin_items = items.select { |k, _| k == :plugin }
+
+          # No plugins at this position -> keep as-is
+          if plugin_items.empty?
+            result.concat(items)
+            next
+          end
+
+          # Rule 1: plugin overrides method insertion at the same position
+          items = items.reject { |k, _| k == :method }
+
+          # Rule 2: keep only highest-priority plugin insertions
+          max_prio = plugin_items.map { |_k, ins| plugin_insertion_priority(ins) }.max || 0
+
+          items = items.reject do |k, ins|
+            k == :plugin && plugin_insertion_priority(ins) < max_prio
+          end
+
+          # Warn on ties between different plugins at the winning priority
+          if Docscribe::Plugin.debug?
+            kept_plugin_labels =
+              items
+              .select { |k, _| k == :plugin }
+              .map { |_k, ins| plugin_insertion_label(ins) }
+              .uniq
+
+            if kept_plugin_labels.size > 1
+              line = plugin_insertion_line(plugin_items.first[1])
+              loc = +"pos=#{pos}"
+              loc << " line=#{line}" if line
+
+              warn "Docscribe: CollectorPlugin conflict at #{loc} (priority=#{max_prio}): " \
+                   "#{kept_plugin_labels.join(', ')} — keeping all. Set explicit priority to resolve."
+            end
+          end
+
+          result.concat(items)
+        end
+
+        result
+      end
+
+      # @private
+      # @param [Hash] insertion
+      # @raise [StandardError]
+      # @return [Integer]
+      def plugin_insertion_priority(insertion)
+        return 0 unless insertion.is_a?(Hash)
+
+        Integer(insertion[:__docscribe_priority] || 0)
+      rescue StandardError
+        0
+      end
+
+      # @private
+      # @param [Hash] insertion
+      # @raise [StandardError]
+      # @return [String]
+      def plugin_insertion_label(insertion)
+        return 'unknown' unless insertion.is_a?(Hash)
+
+        label = insertion[:__docscribe_plugin_class].to_s
+        label.empty? ? 'unknown' : label
+      rescue StandardError
+        'unknown'
+      end
+
+      # @private
+      # @param [Hash] insertion
+      # @raise [StandardError]
+      # @return [Integer, nil]
+      def plugin_insertion_line(insertion)
+        return nil unless insertion.is_a?(Hash)
+
+        insertion[:anchor_node]&.loc&.expression&.line
+      rescue StandardError
+        nil
+      end
+
       # Resolve the source begin_pos for sorting, handling both Struct-based
       # insertions (method/attr) and Hash-based insertions (plugin).
       #
@@ -239,7 +344,7 @@ module Docscribe
         Parser::Source::Range.new(buffer, start_pos, bol_pos)
       end
 
-      # Normalise indentation of a plugin-generated doc block.
+      # Normalize indentation of a plugin-generated doc block.
       #
       # Plugins produce doc strings without knowledge of the surrounding
       # indentation. We strip leading whitespace from each non-empty line

data/lib/docscribe/plugin/registry.rb

@@ -11,8 +11,22 @@ module Docscribe
     # Thread safety: registration is expected to happen before any parallel
     # rewriting begins.
     module Registry
-      @tag_plugins = []
-      @collector_plugins = []
+      # @!attribute [rw] plugin
+      #   @return [Object]
+      #   @param [Object] value
+      #
+      # @!attribute [rw] priority
+      #   @return [Object]
+      #   @param [Object] value
+      #
+      # @!attribute [rw] order
+      #   @return [Object]
+      #   @param [Object] value
+      Entry = Struct.new(:plugin, :priority, :order, keyword_init: true)
+
+      @tag_entries = []
+      @collector_entries = []
+      @order_seq = 0
 
       module_function
 
@@ -26,13 +40,25 @@ module Docscribe
       #
       # @note module_function: when included, also defines #register (instance visibility: private)
       # @param [Object] plugin plugin instance
+      # @param [Integer] priority plugin priority (higher wins for conflicts)
       # @raise [ArgumentError] if plugin type cannot be determined
+      # @raise [StandardError]
       # @return [void]
-      def register(plugin)
+      def register(plugin, priority: 0)
+        prio =
+          begin
+            Integer(priority)
+          rescue StandardError
+            raise ArgumentError, "priority must be an Integer-like value, got: #{priority.inspect}"
+          end
+
+        @order_seq += 1
+        entry = Entry.new(plugin: plugin, priority: prio, order: @order_seq)
+
         if plugin.is_a?(Base::CollectorPlugin) || plugin.respond_to?(:collect)
-          @collector_plugins << plugin
+          @collector_entries << entry
         elsif plugin.is_a?(Base::TagPlugin) || plugin.respond_to?(:call)
-          @tag_plugins << plugin
+          @tag_entries << entry
         else
           raise ArgumentError, 'Plugin must respond to #call (TagPlugin) or #collect (CollectorPlugin)'
         end
@@ -43,7 +69,7 @@ module Docscribe
       # @note module_function: when included, also defines #tag_plugins (instance visibility: private)
       # @return [Array<#call>]
       def tag_plugins
-        @tag_plugins.dup
+        @tag_entries.map(&:plugin)
       end
 
       # All registered collector plugins in registration order.
@@ -51,7 +77,23 @@ module Docscribe
       # @note module_function: when included, also defines #collector_plugins (instance visibility: private)
       # @return [Array<#collect>]
       def collector_plugins
-        @collector_plugins.dup
+        @collector_entries.map(&:plugin)
+      end
+
+      # All registered tag plugin entries (plugin + priority metadata).
+      #
+      # @note module_function: when included, also defines #tag_entries (instance visibility: private)
+      # @return [Array<Entry>]
+      def tag_entries
+        @tag_entries.dup
+      end
+
+      # All registered collector plugin entries (plugin + priority metadata).
+      #
+      # @note module_function: when included, also defines #collector_entries (instance visibility: private)
+      # @return [Array<Entry>]
+      def collector_entries
+        @collector_entries.dup
       end
 
       # Remove all registered plugins.
@@ -61,8 +103,9 @@ module Docscribe
       # @note module_function: when included, also defines #clear! (instance visibility: private)
       # @return [void]
       def clear!
-        @tag_plugins.clear
-        @collector_plugins.clear
+        @tag_entries.clear
+        @collector_entries.clear
+        @order_seq = 0
       end
     end
   end

data/lib/docscribe/plugin.rb

@@ -27,7 +27,13 @@ module Docscribe
     # @raise [StandardError]
     # @return [Array<Docscribe::Plugin::Tag>]
     def self.run_tag_plugins(context)
-      Registry.tag_plugins.flat_map do |plugin|
+      Registry.tag_entries
+              # Higher number => higher priority (run earlier).
+              # This matters when multiple TagPlugins emit the same tag name
+              # and Docscribe deduplicates tags by name.
+              .sort_by { |entry| [-entry.priority, entry.order] }
+              .flat_map do |entry|
+        plugin = entry.plugin
         plugin.call(context)
       rescue StandardError => e
         warn "Docscribe: TagPlugin #{plugin.class} raised #{e.class}: #{e.message}" if debug?
@@ -42,8 +48,21 @@ module Docscribe
     # @raise [StandardError]
     # @return [Array<Hash>]
     def self.run_collector_plugins(ast, buffer)
-      Registry.collector_plugins.flat_map do |plugin|
-        plugin.collect(ast, buffer)
+      Registry.collector_entries.flat_map do |entry|
+        plugin = entry.plugin
+
+        Array(plugin.collect(ast, buffer)).map do |insertion|
+          unless insertion.is_a?(Hash)
+            warn "Docscribe: CollectorPlugin #{plugin.class} returned #{insertion.class}, expected Hash" if debug?
+            next nil
+          end
+
+          insertion.merge(
+            __docscribe_priority: entry.priority,
+            __docscribe_plugin_class: plugin.class.name,
+            __docscribe_plugin_order: entry.order
+          )
+        end.compact
       rescue StandardError => e
         warn "Docscribe: CollectorPlugin #{plugin.class} raised #{e.class}: #{e.message}" if debug?
         []

data/lib/docscribe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docscribe
-  VERSION = '1.3.3'
+  VERSION = '1.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docscribe
 version: !ruby/object:Gem::Version
-  version: 1.3.3
+  version: 1.4.0
 platform: ruby
 authors:
 - unurgunite