docscribe 1.3.3 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 755d272674fe454b80cc008acb50a879da920def321442cdc8cdd7c450b91f52
-  data.tar.gz: 92aa2320a36162272acfa2b430bfa9cccf5a4582770885a996bc61d7a4198bb6
+  metadata.gz: e59e0f95a3faa67d4d9d7829ed32e2acd30f3fa5b3236f93d4b5f8bb63ae7616
+  data.tar.gz: cae706be421e11e31c6124a5e918c407b09a0cdd4435c2ad2d427b63ea4a9f80
 SHA512:
-  metadata.gz: 9268725904b6644b4d46a89c72cda271c4d1b5fedc5066396af1515fa955fecb864fad10406db81582391f81d5265595c7c2bb6fe5793bfc1c7b465395937577
-  data.tar.gz: e8012b3c09ec75e8bd7bbed32f51b297edb2d081b65b2bdf849667e1c7cdb5469862697ddc060c8194b4bf08cc671cb61b6b94507ca382841745e27923963513
+  metadata.gz: c864edd9a99ad81667030ccfc13936ebb8d13948528bc288235aa2e4ff0de349b16eb3bf3f2b9606d33c8af9129357639a29db319e0c62bddd6ec1df997a7fea
+  data.tar.gz: 4c62242b2455c5a6117ba4e1f02335b911b4894c6f15aa852c704d9583cd89ca6e0439fcc4cee6d6b3decb6e33afb75c90effa71a5a24c9e39f3fe56e0245a35

data/README.md

@@ -68,7 +68,10 @@ Common workflows:
     * [Plugin system](#plugin-system)
         * [TagPlugin](#tagplugin)
         * [CollectorPlugin](#collectorplugin)
+            * [Plugin doc normalization (CollectorPlugin)](#plugin-doc-normalization-collectorplugin)
+            * [`method_override` (structured patch)](#method_override-structured-patch)
         * [Registering plugins](#registering-plugins)
+        * [Plugin priority](#plugin-priority)
         * [Idempotency](#idempotency)
         * [Plugin examples](#plugin-examples)
     * [Configuration](#configuration)
@@ -865,17 +868,49 @@ class DefineMethodPlugin < Docscribe::Plugin::Base::CollectorPlugin
 end
 ```
 
-Each result hash must have:
+Each result hash must have `:anchor_node` plus either `:doc` or `:method_override`:
 
-| Key            | Type                | Description                                |
-|----------------|---------------------|--------------------------------------------|
-| `:anchor_node` | `Parser::AST::Node` | Node above which to insert the doc block   |
-| `:doc`         | `String`            | Complete doc block text including newlines |
+| Key                | Type                | Description                                                                                                             |
+|--------------------|---------------------|-------------------------------------------------------------------------------------------------------------------------|
+| `:anchor_node`     | `Parser::AST::Node` | Node above which to insert the doc block                                                                                |
+| `:doc`             | `String`            | Complete doc block text including newlines (Docscribe may normalize indentation and default message for method anchors) |
+| `:method_override` | `Hash`              | Structured overrides that patch the standard DocBuilder output instead of replacing it (see below)                      |
 
 > [!NOTE]
 > You do not need to handle indentation manually. Docscribe reads the indentation from `anchor_node` and applies it to
 > every line of `:doc` automatically.
 
+#### Plugin doc normalization (CollectorPlugin)
+
+When returning `doc:`, CollectorPlugins provide raw strings that Docscribe inserts without running the standard
+method DocBuilder pipeline. Docscribe does normalize indentation and may prepend the default method message for
+`def/defs` anchors, but headers (`emit.header`) and param/return tags must be included explicitly.
+
+#### `method_override` (structured patch)
+
+When a CollectorPlugin targets a `def` method, it can return `method_override:` instead of `doc:` to patch the
+standard DocBuilder output rather than replace it entirely:
+
+```ruby
+{
+  anchor_node: node,
+  method_override: {
+    return_type: 'ActiveRecord::Relation', # overrides @return
+    param_types: { 'period' => 'Integer' }, # merges into @param types
+    tags: [Docscribe::Plugin::Tag.new(name: 'since', text: '2.0')] # additional tags
+  }
+}
+```
+
+| Key            | Type                   | Description                                                 |
+|----------------|------------------------|-------------------------------------------------------------|
+| `:return_type` | `String`               | Overrides the `@return` type name                           |
+| `:param_types` | `Hash{String=>String}` | Merges into inferred param types (external sig wins)        |
+| `:tags`        | `Array<Tag/Hash>`      | Tags appended to the doc block (Hash auto-converted to Tag) |
+
+`method_override` merges at the data level before rendering, so the standard pipeline still generates headers,
+`@param` tags, default messages, and tag sorting. Only the specified fields are overridden.
+
 ### Registering plugins
 
 Plugins are registered at load time. The recommended pattern is to put registrations in a dedicated file and reference
@@ -900,8 +935,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 +960,36 @@ 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):**
+
+- For `doc:` insertions: 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.
+- For `method_override:` insertions: the method insertion is kept and patched with the override data. The standard
+  DocBuilder pipeline still runs (generating `@param`, headers, etc.), and only the specified fields are overridden.
+- If multiple CollectorPlugins target 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 +1003,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/options.rb

@@ -203,6 +203,7 @@ module Docscribe
       # @return [Boolean]
       def looks_like_file_pattern?(pat)
         return false if pat.start_with?('/') && pat.end_with?('/') && pat.length >= 2
+        return false if pat.match?(%r{\A\*/})
 
         pat.include?('/') || pat.include?('**') || pat.end_with?('.rb')
       end

data/lib/docscribe/config/utils.rb

@@ -65,7 +65,7 @@ module Docscribe
     #
     # Supports:
     # - `/regex/`
-    # - shell-style glob patterns
+    # - shell-style glob patterns (with `/` translated to `#` since method IDs use `#`)
     #
     # @private
     # @param [String] pattern
@@ -75,7 +75,7 @@ module Docscribe
       if pattern.start_with?('/') && pattern.end_with?('/') && pattern.length >= 2
         Regexp.new(pattern[1..-2]).match?(text)
       else
-        File.fnmatch?(pattern, text, File::FNM_EXTGLOB)
+        File.fnmatch?(pattern.tr('/', '#'), text, File::FNM_EXTGLOB)
       end
     end
 

data/lib/docscribe/inline_rewriter/doc_builder.rb

@@ -30,9 +30,11 @@ module Docscribe
       #   `signature_for(container:, scope:, name:)`
       # @param [nil] core_rbs_provider Param documentation.
       # @param [nil] param_types Param documentation.
+      # @param [nil] return_type_override Param documentation.
+      # @param [nil] override_tags Param documentation.
       # @raise [StandardError]
       # @return [String, nil]
-      def build(insertion, config:, signature_provider: nil, core_rbs_provider: nil, param_types: nil)
+      def build(insertion, config:, signature_provider: nil, core_rbs_provider: nil, param_types: nil, return_type_override: nil, override_tags: nil)
         node = insertion.node
         name = SourceHelpers.node_name(node)
         return nil unless name
@@ -53,7 +55,7 @@ module Docscribe
           param_types || build_param_types_from_node(node, external_sig: external_sig, config: config)
 
         if config.emit_param_tags?
-          params_lines = build_params_lines(node, indent, external_sig: external_sig, config: config)
+          params_lines = build_params_lines(node, indent, external_sig: external_sig, config: config, param_types_override: effective_param_types)
         end
         raise_types = config.emit_raise_tags? ? Docscribe::Infer.infer_raises_from_node(node) : []
 
@@ -65,7 +67,7 @@ module Docscribe
           core_rbs_provider: core_rbs_provider
         )
 
-        normal_type = external_sig&.return_type || returns_spec[:normal]
+        normal_type = return_type_override || external_sig&.return_type || returns_spec[:normal]
         rescue_specs = returns_spec[:rescues] || []
 
         lines = []
@@ -110,9 +112,9 @@ module Docscribe
             lines << "#{indent}# @return [#{rtype}] if #{exceptions.join(', ')}"
           end
         end
-        plugin_tags = Docscribe::Plugin.run_tag_plugins(
-          build_plugin_context(insertion, normal_type: normal_type)
-        )
+        plugin_tags = Docscribe::Plugin.run_tag_plugins(build_plugin_context(insertion, normal_type: normal_type))
+        plugin_tags.concat(Array(override_tags)) if override_tags
+
         lines.concat(render_plugin_tags(plugin_tags, indent))
         lines.map { |l| "#{l}\n" }.join
       rescue StandardError => e
@@ -132,10 +134,11 @@ module Docscribe
       # @param [Object, nil] signature_provider
       # @param [nil] core_rbs_provider Param documentation.
       # @param [nil] param_types Param documentation.
+      # @param [nil] return_type_override Param documentation.
       # @raise [StandardError]
       # @return [String, nil]
       def build_merge_additions(insertion, existing_lines:, config:, signature_provider: nil, core_rbs_provider: nil,
-                                param_types: nil)
+                                param_types: nil, return_type_override: nil)
         node = insertion.node
         name = SourceHelpers.node_name(node)
         return '' unless name
@@ -159,7 +162,7 @@ module Docscribe
           core_rbs_provider: core_rbs_provider
         )
 
-        normal_type = external_sig&.return_type || returns_spec[:normal]
+        normal_type = return_type_override || external_sig&.return_type || returns_spec[:normal]
         rescue_specs = returns_spec[:rescues] || []
 
         lines = []
@@ -180,7 +183,7 @@ module Docscribe
         end
 
         if config.emit_param_tags?
-          all_params = build_params_lines(node, indent, external_sig: external_sig, config: config)
+          all_params = build_params_lines(node, indent, external_sig: external_sig, config: config, param_types_override: param_types)
           all_params&.each do |pl|
             pname = extract_param_name_from_param_line(pl)
             next if pname.nil? || info[:param_names].include?(pname)
@@ -229,10 +232,12 @@ module Docscribe
       # @param [nil] core_rbs_provider Param documentation.
       # @param [nil] param_types Param documentation.
       # @param [nil] strategy Param documentation.
+      # @param [nil] return_type_override Param documentation.
+      # @param [nil] override_tags Param documentation.
       # @raise [StandardError]
       # @return [Hash]
       def build_missing_merge_result(insertion, existing_lines:, config:, signature_provider: nil,
-                                     core_rbs_provider: nil, param_types: nil, strategy: nil)
+                                     core_rbs_provider: nil, param_types: nil, strategy: nil, return_type_override: nil, override_tags: nil)
         node = insertion.node
         name = SourceHelpers.node_name(node)
         return { lines: [], reasons: [] } unless name
@@ -256,7 +261,7 @@ module Docscribe
           core_rbs_provider: core_rbs_provider
         )
 
-        normal_type = external_sig&.return_type || returns_spec[:normal]
+        normal_type = return_type_override || external_sig&.return_type || returns_spec[:normal]
         rescue_specs = returns_spec[:rescues] || []
 
         lines = []
@@ -280,7 +285,7 @@ module Docscribe
         end
 
         if config.emit_param_tags?
-          all_params = build_params_lines(node, indent, external_sig: external_sig, config: config)
+          all_params = build_params_lines(node, indent, external_sig: external_sig, config: config, param_types_override: param_types)
 
           all_params&.each do |pl|
             pname = extract_param_name_from_param_line(pl)
@@ -336,9 +341,9 @@ module Docscribe
             }
           end
         end
-        plugin_tags = Docscribe::Plugin.run_tag_plugins(
-          build_plugin_context(insertion, normal_type: normal_type)
-        )
+        plugin_tags = Docscribe::Plugin.run_tag_plugins(build_plugin_context(insertion, normal_type: normal_type))
+        plugin_tags.concat(Array(override_tags)) if override_tags
+
         plugin_tags.each do |tag|
           next if info[:plugin_tags]&.[](tag.name)
 
@@ -523,8 +528,9 @@ module Docscribe
       # @param [String] indent
       # @param [Docscribe::Types::MethodSignature, nil] external_sig
       # @param [Docscribe::Config] config
+      # @param [nil] param_types_override Param documentation.
       # @return [Array<String>, nil]
-      def build_params_lines(node, indent, external_sig:, config:)
+      def build_params_lines(node, indent, external_sig:, config:, param_types_override: nil)
         fallback_type = config.fallback_type
         treat_options_keyword_as_hash = config.treat_options_keyword_as_hash?
         param_tag_style = config.param_tag_style
@@ -545,6 +551,7 @@ module Docscribe
           when :arg
             pname = a.children.first.to_s
             ty = external_sig&.param_types&.[](pname) ||
+                 override_param_type_for(pname, param_types_override) ||
                  Infer.infer_param_type(
                    pname,
                    nil,
@@ -558,6 +565,7 @@ module Docscribe
             pname = pname.to_s
             default_src = default&.loc&.expression&.source
             ty = external_sig&.param_types&.[](pname) ||
+                 override_param_type_for(pname, param_types_override) ||
                  Infer.infer_param_type(
                    pname,
                    default_src,
@@ -581,6 +589,7 @@ module Docscribe
           when :kwarg
             pname = a.children.first.to_s
             ty = external_sig&.param_types&.[](pname) ||
+                 override_param_type_for(pname, param_types_override) ||
                  Infer.infer_param_type(
                    "#{pname}:",
                    nil,
@@ -594,6 +603,7 @@ module Docscribe
             pname = pname.to_s
             default_src = default&.loc&.expression&.source
             ty = external_sig&.param_types&.[](pname) ||
+                 override_param_type_for(pname, param_types_override) ||
                  Infer.infer_param_type(
                    "#{pname}:",
                    default_src,
@@ -608,18 +618,20 @@ module Docscribe
               if external_sig&.rest_positional&.element_type
                 "Array<#{external_sig.rest_positional.element_type}>"
               else
-                Infer.infer_param_type(
-                  "*#{pname}",
-                  nil,
-                  fallback_type: fallback_type,
-                  treat_options_keyword_as_hash: treat_options_keyword_as_hash
-                )
+                override_param_type_for(pname, param_types_override) ||
+                  Infer.infer_param_type(
+                    "*#{pname}",
+                    nil,
+                    fallback_type: fallback_type,
+                    treat_options_keyword_as_hash: treat_options_keyword_as_hash
+                  )
               end
             params << format_param_tag(indent, pname, ty, param_documentation, style: param_tag_style)
 
           when :kwrestarg
             pname = (a.children.first || 'kwargs').to_s
             ty = external_sig&.rest_keywords&.type ||
+                 override_param_type_for(pname, param_types_override) ||
                  Infer.infer_param_type(
                    "**#{pname}",
                    nil,
@@ -631,6 +643,7 @@ module Docscribe
           when :blockarg
             pname = (a.children.first || 'block').to_s
             ty = external_sig&.param_types&.[](pname) ||
+                 override_param_type_for(pname, param_types_override) ||
                  Infer.infer_param_type(
                    "&#{pname}",
                    nil,
@@ -647,6 +660,19 @@ module Docscribe
         params.empty? ? nil : params
       end
 
+      # Method documentation.
+      #
+      # @note module_function: when included, also defines #override_param_type_for (instance visibility: private)
+      # @param [Object] pname Param documentation.
+      # @param [Object] override_map Param documentation.
+      # @return [Object]
+      def override_param_type_for(pname, override_map)
+        return nil unless override_map
+
+        key = pname.to_s
+        override_map[key] || override_map[:"#{key}"] || override_map["#{key}:"] || override_map[:"#{key}:"]
+      end
+
       # Format a `@param` tag line using the configured param tag style.
       #
       # @note module_function: when included, also defines #format_param_tag (instance visibility: private)

data/lib/docscribe/inline_rewriter.rb

@@ -72,7 +72,7 @@ module Docscribe
       # @raise [Docscribe::ParseError]
       # @raise [StandardError]
       # @return [Hash]
-      def rewrite_with_report(code, strategy: nil, rewrite: nil, merge: nil, config: Docscribe::Config.new({}),
+      def rewrite_with_report(code, strategy: nil, rewrite: nil, merge: nil, config: nil,
                               core_rbs_provider: nil, file: '(inline)')
         strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)
         validate_strategy!(strategy)
@@ -102,6 +102,9 @@ module Docscribe
         all = method_insertions.map { |i| [:method, i] } +
               attr_insertions.map { |i| [:attr, i] } +
               plugin_insertions.map { |i| [:plugin, i] }
+
+        method_overrides_by_pos = {}
+        all = deduplicate_insertions(all, method_overrides_by_pos: method_overrides_by_pos)
         rewriter = Parser::Source::TreeRewriter.new(buffer)
         merge_inserts = Hash.new { |h, k| h[k] = [] }
         changes = []
@@ -110,6 +113,9 @@ module Docscribe
            .reverse_each do |kind, ins|
           case kind
           when :method
+            pos = plugin_insertion_pos(:method, ins)
+            method_override = method_overrides_by_pos[pos]
+
             apply_method_insertion!(
               rewriter: rewriter,
               buffer: buffer,
@@ -119,7 +125,8 @@ module Docscribe
               core_rbs_provider: core_rbs_provider,
               strategy: strategy,
               changes: changes,
-              file: file.to_s
+              file: file.to_s,
+              method_override: method_override
             )
           when :attr
             apply_attr_insertion!(
@@ -136,7 +143,8 @@ module Docscribe
               rewriter: rewriter,
               buffer: buffer,
               insertion: ins,
-              strategy: strategy
+              strategy: strategy,
+              config: config
             )
           end
         end
@@ -148,6 +156,181 @@ 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
+      # @param [nil] method_overrides_by_pos Param documentation.
+      # @return [Array<Array(Symbol,Object)>]
+      def deduplicate_insertions(insertions, method_overrides_by_pos: nil)
+        groups = {}
+
+        insertions.each do |kind, ins|
+          pos = plugin_insertion_pos(kind, ins)
+          (groups[pos] ||= []) << [kind, ins]
+        end
+
+        result = []
+
+        groups.each do |pos, items|
+          # plugin insertions at this pos
+          plugin_items = items.select { |k, _| k == :plugin }
+
+          # no plugins -> keep as-is
+          if plugin_items.empty?
+            result.concat(items)
+            next
+          end
+
+          method_items = items.select { |k, _| k == :method }
+
+          plugin_doc_items =
+            plugin_items.select do |_k, ins|
+              ins.is_a?(Hash) && ins[:doc] && !ins[:doc].empty?
+            end
+
+          override_items =
+            plugin_items.select do |_k, ins|
+              ins.is_a?(Hash) && ins[:method_override].is_a?(Hash)
+            end
+
+          # --- Case A: raw plugin doc exists => legacy behavior: plugin replaces method ---
+          if plugin_doc_items.any?
+            # drop standard method insertions at same pos
+            items = items.reject { |k, _| k == :method }
+
+            # drop method_overrides too (they have nothing to patch)
+            items = items.reject { |k, ins| k == :plugin && ins.is_a?(Hash) && ins.key?(:method_override) }
+
+            # keep only highest-priority plugin docs
+            max_prio = plugin_doc_items.map { |_k, ins| plugin_insertion_priority(ins) }.max || 0
+
+            dropped = items.select { |k, ins| k == :plugin && ins.is_a?(Hash) && ins[:doc] && plugin_insertion_priority(ins) < max_prio }
+
+            items = items.reject do |k, ins|
+              k == :plugin && ins.is_a?(Hash) && ins[:doc] && plugin_insertion_priority(ins) < max_prio
+            end
+
+            if Docscribe::Plugin.debug? && dropped.any?
+              kept_labels = items.select { |k, _| k == :plugin }
+                                 .map { |_k, ins| plugin_insertion_label(ins) }
+                                 .uniq
+              dropped_labels = dropped.map { |_k, ins| plugin_insertion_label(ins) }.uniq
+              line = plugin_insertion_line(plugin_items.first[1])
+              loc = +"pos=#{pos}"
+              loc << " line=#{line}" if line
+              warn "Docscribe: CollectorPlugin conflict at #{loc} — " \
+                   "#{dropped_labels.join(', ')} (pri=#{dropped.map { |_k, ins| plugin_insertion_priority(ins) }.max}) " \
+                   "dropped in favor of #{kept_labels.join(', ')} (pri=#{max_prio}). " \
+                   'Set explicit priority or adjust anchor_node to avoid collision.'
+            end
+
+            result.concat(items)
+            next
+          end
+
+          # --- Case B: method_override exists and there is a method insertion => patch method ---
+          if override_items.any? && method_items.any?
+            if method_overrides_by_pos
+              winning_ins = pick_highest_priority_override_insertion(override_items, pos: pos)
+              method_overrides_by_pos[pos] = winning_ins[:method_override] if winning_ins
+            end
+
+            # remove override items from final insertions (they are applied via method_overrides_by_pos)
+            items = items.reject { |k, ins| k == :plugin && ins.is_a?(Hash) && ins.key?(:method_override) }
+
+            result.concat(items)
+            next
+          end
+
+          # --- Case C: override exists, but no method insertion (filtered out, etc.) => ignore override ---
+          items = items.reject { |k, ins| k == :plugin && ins.is_a?(Hash) && ins.key?(:method_override) }
+          result.concat(items)
+        end
+
+        result
+      end
+
+      # @private
+      # @param override_items [Array<Array(Symbol, Hash)>] list of [:plugin, insertion_hash] that include :method_override
+      # @param pos [Integer] begin_pos (used only for debug output)
+      # @return [Hash, nil] winning insertion hash (the one whose override will be applied)
+      def pick_highest_priority_override_insertion(override_items, pos:)
+        return nil if override_items.empty?
+
+        max_prio =
+          override_items.map { |_k, ins| plugin_insertion_priority(ins) }.max || 0
+
+        winners =
+          override_items.select { |_k, ins| plugin_insertion_priority(ins) == max_prio }
+
+        # Deterministic tie-break: smallest plugin order wins.
+        # (We warn in debug if the tie is between different plugins.)
+        winners_sorted =
+          winners.sort_by do |_k, ins|
+            order = ins.is_a?(Hash) ? ins[:__docscribe_plugin_order] : nil
+            order.nil? ? 0 : order
+          end
+
+        if Docscribe::Plugin.debug?
+          labels = winners_sorted.map { |_k, ins| plugin_insertion_label(ins) }.uniq
+          if labels.size > 1
+            line = plugin_insertion_line(winners_sorted.first[1])
+            loc = +"pos=#{pos}"
+            loc << " line=#{line}" if line
+            warn "Docscribe: method_override conflict at #{loc} (priority=#{max_prio}): " \
+                 "#{labels.join(', ')} — using first by registration order."
+          end
+        end
+
+        winners_sorted.first[1]
+      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).
       #
@@ -174,14 +357,15 @@ module Docscribe
       # @param [Parser::Source::Buffer] buffer
       # @param [Hash] insertion { anchor_node:, doc: }
       # @param [Symbol] strategy
+      # @param [Docscribe::Config] config
       # @return [void]
-      def apply_plugin_insertion!(rewriter:, buffer:, insertion:, strategy:)
+      def apply_plugin_insertion!(rewriter:, buffer:, insertion:, strategy:, config:)
         anchor_node = insertion[:anchor_node]
         doc         = insertion[:doc]
         return unless anchor_node && doc && !doc.empty?
 
         indent = SourceHelpers.line_indent(anchor_node)
-        doc    = normalize_plugin_doc_indent(doc, indent)
+        doc    = normalize_plugin_doc(doc, indent, config: config, anchor_node: anchor_node)
         bol_range = SourceHelpers.line_start_range(buffer, anchor_node)
 
         case strategy
@@ -239,7 +423,51 @@ module Docscribe
         Parser::Source::Range.new(buffer, start_pos, bol_pos)
       end
 
-      # Normalise indentation of a plugin-generated doc block.
+      # Normalize a CollectorPlugin-provided doc string before insertion.
+      #
+      # Responsibilities:
+      # - apply indentation based on the anchor node
+      # - trim trailing whitespace-only lines
+      # - (optionally) prepend the configured default message for `def/defs` anchors
+      #   when the plugin output contains only tags (no prose)
+      #
+      # @private
+      # @param doc [String] Raw doc string returned by a CollectorPlugin insertion (`:doc`)
+      # @param indent [String] Indentation to apply to every doc line
+      # @param config [Docscribe::Config] Effective Docscribe config for this run
+      # @param anchor_node [Parser::AST::Node, nil] AST node used as insertion anchor
+      # @return [String] Normalized doc string ready to be inserted
+      def normalize_plugin_doc(doc, indent, config:, anchor_node:)
+        doc = normalize_plugin_doc_indent(doc, indent)
+
+        lines = doc.lines
+        lines.pop while lines.any? && lines.last.strip.empty?
+
+        doc = lines.join
+        doc << "\n" unless doc.end_with?("\n")
+
+        if %i[def defs].include?(anchor_node&.type) && config.include_default_message?
+          scope = anchor_node.type == :defs ? :class : :instance
+          msg = config.default_message(scope, :public)
+
+          has_prose = doc.lines.any? do |l|
+            s = l.strip
+            next false if s.empty? || s == '#'
+            next false if s.start_with?('# @')      # tag line
+            next false if s.start_with?('# +')      # header line
+
+            true
+          end
+
+          unless has_prose
+            doc = "#{indent}# #{msg}\n#{indent}#\n" + doc
+          end
+        end
+
+        doc
+      end
+
+      # 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
@@ -309,9 +537,10 @@ module Docscribe
       # @param [Array<Hash>] changes structured change records
       # @param [String] file
       # @param [Object] core_rbs_provider Param documentation.
+      # @param [nil] method_override Param documentation.
       # @return [void]
       def apply_method_insertion!(rewriter:, buffer:, insertion:, config:, signature_provider:, core_rbs_provider:,
-                                  strategy:, changes:, file:)
+                                  strategy:, changes:, file:, method_override: nil)
         name = SourceHelpers.node_name(insertion.node)
 
         return unless config.process_method?(
@@ -329,6 +558,24 @@ module Docscribe
           scope: insertion.scope,
           name: SourceHelpers.node_name(insertion.node)
         )
+        override_return_type =
+          method_override.is_a?(Hash) ? method_override[:return_type] : nil
+
+        override_param_types =
+          method_override.is_a?(Hash) && method_override[:param_types].is_a?(Hash) ? method_override[:param_types] : nil
+
+        override_tags =
+          if method_override.is_a?(Hash)
+            Array(method_override[:tags]).filter_map do |t|
+              case t
+              when Docscribe::Plugin::Tag then t
+              when Hash
+                Docscribe::Plugin::Tag.new(**t.transform_keys(&:to_sym))
+              end
+            end
+          else
+            []
+          end
 
         case strategy
         when :aggressive
@@ -342,8 +589,20 @@ module Docscribe
             config: config
           )
 
-          doc = build_method_doc(insertion, config: config, signature_provider: signature_provider,
-                                            core_rbs_provider: core_rbs_provider, param_types: effective_param_types)
+          if override_param_types && !override_param_types.empty?
+            effective_param_types = effective_param_types.merge(override_param_types)
+          end
+
+          doc = build_method_doc(
+            insertion,
+            config: config,
+            signature_provider: signature_provider,
+            core_rbs_provider: core_rbs_provider,
+            param_types: effective_param_types,
+            return_type_override: override_return_type,
+            override_tags: override_tags
+          )
+
           return if doc.nil? || doc.empty?
 
           rewriter.insert_before(anchor_bol_range, doc)
@@ -359,6 +618,16 @@ module Docscribe
         when :safe
           info = method_doc_comment_info(buffer, insertion)
 
+          effective_param_types = external_sig&.param_types || DocBuilder.build_param_types_from_node(
+            insertion.node,
+            external_sig: external_sig,
+            config: config
+          )
+
+          if override_param_types && !override_param_types.empty?
+            effective_param_types = effective_param_types.merge(override_param_types)
+          end
+
           if info
             merge_result = build_missing_method_merge_result(
               insertion,
@@ -366,8 +635,10 @@ module Docscribe
               config: config,
               signature_provider: signature_provider,
               core_rbs_provider: core_rbs_provider,
-              param_types: external_sig&.param_types,
-              strategy: strategy
+              param_types: effective_param_types,
+              strategy: strategy,
+              return_type_override: override_return_type,
+              override_tags: override_tags
             )
 
             missing_lines = merge_result[:lines]
@@ -424,9 +695,15 @@ module Docscribe
             return
           end
 
-          doc = build_method_doc(insertion, config: config, signature_provider: signature_provider,
-                                            core_rbs_provider: core_rbs_provider,
-                                            param_types: external_sig&.param_types)
+          doc = build_method_doc(
+            insertion,
+            config: config,
+            signature_provider: signature_provider,
+            core_rbs_provider: core_rbs_provider,
+            param_types: effective_param_types,
+            return_type_override: override_return_type,
+            override_tags: override_tags
+          )
           return if doc.nil? || doc.empty?
 
           rewriter.insert_before(anchor_bol_range, doc)
@@ -773,14 +1050,19 @@ module Docscribe
       # @param [Object, nil] signature_provider external signature provider
       # @param [Object, nil] core_rbs_provider RBS core type provider
       # @param [Hash, nil] param_types parameter name -> type map
+      # @param [Object] return_type_override Param documentation.
+      # @param [Object] override_tags Param documentation.
       # @return [String, nil] generated doc block or nil
-      def build_method_doc(insertion, config:, signature_provider:, core_rbs_provider:, param_types:)
+      def build_method_doc(insertion, config:, signature_provider:, core_rbs_provider:, param_types:, return_type_override:,
+                           override_tags:)
         DocBuilder.build(
           insertion,
           config: config,
           signature_provider: signature_provider,
           core_rbs_provider: core_rbs_provider,
-          param_types: param_types
+          param_types: param_types,
+          return_type_override: return_type_override,
+          override_tags: override_tags
         )
       end
 
@@ -794,9 +1076,11 @@ module Docscribe
       # @param [Object, nil] core_rbs_provider RBS core type provider
       # @param [Hash, nil] param_types parameter name -> type map
       # @param [Object] strategy Param documentation.
+      # @param [Object] return_type_override Param documentation.
+      # @param [nil] override_tags Param documentation.
       # @return [Hash] result with `:lines` and `:reasons` keys
       def build_missing_method_merge_result(insertion, existing_lines:, config:, signature_provider:,
-                                            core_rbs_provider:, param_types:, strategy:)
+                                            core_rbs_provider:, param_types:, strategy:, return_type_override:, override_tags: nil)
         DocBuilder.build_missing_merge_result(
           insertion,
           existing_lines: existing_lines,
@@ -804,7 +1088,9 @@ module Docscribe
           signature_provider: signature_provider,
           core_rbs_provider: core_rbs_provider,
           param_types: param_types,
-          strategy: strategy
+          strategy: strategy,
+          return_type_override: return_type_override,
+          override_tags: override_tags
         )
       end
 

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.1'
 end

metadata

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