docscribe 1.3.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 765dd81d49b3cbf47c90f83f9e533a367da6590f84b15ca7e49de66c6140b5e1
-  data.tar.gz: b7c0607de2fb6e2344be24d4da58c1e03ab33755175783e1e6de8c934a8f2cdc
+  metadata.gz: 50c74b921731749cbf32726e24e557e526e1f65966e704171a652d10cc4ce945
+  data.tar.gz: 2e254911cf9d81f5d5f7b5df29576c3c5c3c3f0433cfb387c0d22c1ce30eeb60
 SHA512:
-  metadata.gz: f30b33860317c5b9914e6b6c633df75c35f11883d7524c3b832365431a5f47760eaaeb4daab3b20f358bad8cb088015b173d6848bf65b3d7cbba18a69fda5154
-  data.tar.gz: 66ac534ba8452880ee778ae1bf72ce571e9ea4bba481e5595172314df1f809eb62db87ec8b77cd4efb8c8cd37c85dd0c937b7fa8c263938ab46734ae03f5acda
+  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/cli/config_builder.rb

@@ -53,7 +53,7 @@ module Docscribe
             require 'docscribe/types/rbs/collection_loader'
             collection_path = Docscribe::Types::RBS::CollectionLoader.resolve
             if collection_path
-              raw['rbs']['sig_dirs'] = Array(raw['rbs']['sig_dirs']) + [collection_path]
+              raw['rbs']['collection_dirs'] = Array(raw['rbs']['collection_dirs']) + [collection_path]
             else
               warn 'Docscribe: rbs_collection.lock.yaml not found or collection not installed. ' \
                    'Run `bundle exec rbs collection install` first.'

data/lib/docscribe/config/defaults.rb

@@ -62,6 +62,7 @@ module Docscribe
         'enabled' => false,
         'collection' => false,
         'sig_dirs' => ['sig'],
+        'collection_dirs' => [],
         'collapse_generics' => false
       },
       'sorbet' => {

data/lib/docscribe/config/rbs.rb

@@ -17,6 +17,7 @@ module Docscribe
         require 'docscribe/types/rbs/provider'
         Docscribe::Types::RBS::Provider.new(
           sig_dirs: rbs_sig_dirs,
+          collection_dirs: rbs_collection_dirs,
           collapse_generics: rbs_collapse_generics?
         )
       rescue LoadError
@@ -73,6 +74,18 @@ module Docscribe
       Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map(&:to_s)
     end
 
+    # RBS collection directories (auto-discovered from rbs_collection.lock.yaml).
+    #
+    # Loaded separately from user sig_dirs so that collection-related
+    # RBS environment errors (e.g. duplicate declarations against core
+    # stdlib types) do not silence all RBS lookups.
+    #
+    # @private
+    # @return [Array<String>]
+    def rbs_collection_dirs
+      Array(raw.dig('rbs', 'collection_dirs')).map(&:to_s)
+    end
+
     # Whether generic RBS types should be collapsed to simpler container names.
     #
     # Examples:

data/lib/docscribe/config/template.rb

@@ -86,6 +86,7 @@ module Docscribe
           # Use RBS signatures for better types (requires `gem "rbs"`)
           enabled: false
           sig_dirs: ["sig"]
+          collection_dirs: []                 # auto-discovered from --rbs-collection
           collapse_generics: false            # Hash<Symbol, String> => Hash
           collection: false                   # auto-discover from rbs_collection.lock.yaml
 

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/types/rbs/provider.rb

@@ -15,16 +15,21 @@ module Docscribe
       # the pipeline can stay independent of the underlying signature source.
       class Provider
         # @param [Array<String>] sig_dirs directories containing `.rbs` files
+        # @param [Array<String>] collection_dirs RBS collection directories
+        #   (loaded separately; on error they are silently dropped and only
+        #   user sig_dirs are used)
         # @param [Boolean] collapse_generics whether generic container types
         #   should be simplified during formatting
         # @return [Object]
-        def initialize(sig_dirs:, collapse_generics: false)
+        def initialize(sig_dirs:, collection_dirs: [], collapse_generics: false)
           require 'rbs'
           @sig_dirs = Array(sig_dirs).map(&:to_s)
+          @collection_dirs = Array(collection_dirs).map(&:to_s)
           @collapse_generics = !!collapse_generics
           @env = nil
           @builder = nil
           @warned = false
+          @collection_dropped = false
         end
 
         # Look up a normalized method signature from loaded RBS definitions.
@@ -64,22 +69,48 @@ module Docscribe
 
         # Lazily load and resolve the RBS environment.
         #
+        # Tries to load collection dirs together with user sig_dirs.
+        # If the combined environment raises a load error (e.g. duplicate
+        # declarations between collection and core stdlib types), collection
+        # dirs are dropped and only user sig_dirs are used.
+        #
         # @private
+        # @raise [::RBS::BaseError]
+        # @raise [StandardError]
         # @return [void]
         def load_env!
           return if @env && @builder
 
+          @env = build_env(@sig_dirs + @collection_dirs)
+        rescue ::RBS::BaseError => e
+          raise unless @collection_dirs.any? && !@collection_dropped
+
+          @collection_dropped = true
+          if ENV['DOCSCRIBE_RBS_DEBUG'] == '1'
+            warn "Docscribe: RBS collection error (#{e.class}), dropping collection dirs. " \
+                 'Set DOCSCRIBE_RBS_DEBUG=1 for details.'
+          end
+          @env = build_env(@sig_dirs)
+        end
+
+        # Build an RBS environment from the given directories.
+        #
+        # @private
+        # @param [Array<String>] dirs
+        # @return [::RBS::Environment]
+        def build_env(dirs)
           loader = ::RBS::EnvironmentLoader.new
           # Load core types transitively
           loader.add(library: 'rbs')
 
-          @sig_dirs.each do |dir|
+          dirs.each do |dir|
             path = Pathname(dir)
             loader.add(path: path) if path.directory?
           end
 
-          @env = ::RBS::Environment.from_loader(loader).resolve_type_names
-          @builder = ::RBS::DefinitionBuilder.new(env: @env)
+          env = ::RBS::Environment.from_loader(loader).resolve_type_names
+          @builder = ::RBS::DefinitionBuilder.new(env: env)
+          env
         end
 
         # Build the appropriate instance or singleton definition for a container.

data/lib/docscribe/version.rb

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

metadata

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