docscribe 1.4.1 → 1.5.0

data/lib/docscribe/inline_rewriter.rb

@@ -34,270 +34,430 @@ module Docscribe
   # - `rewrite: true` maps to `strategy: :aggressive`
   module InlineRewriter
     class << self
-      # Rewrite source and return only the rewritten output string.
-      #
-      # This is the main convenience entry point for library usage.
+      # Insert comments
       #
       # @param [String] code Ruby source
-      # @param [Symbol, nil] strategy :safe or :aggressive
-      # @param [Boolean, nil] rewrite compatibility alias for aggressive strategy
-      # @param [Boolean, nil] merge compatibility alias for safe strategy
-      # @param [Docscribe::Config, nil] config config object (defaults to loaded config)
-      # @param [String] file source name used for parser locations/debugging
+      # @param [Symbol?] strategy :safe or :aggressive
+      # @param [Boolean?] rewrite compatibility alias for aggressive strategy
+      # @param [Boolean?] merge compatibility alias for safe strategy
+      # @param [Object] options additional keyword arguments forwarded to rewrite_with_report
       # @return [String]
-      def insert_comments(code, strategy: nil, rewrite: nil, merge: nil, config: nil, file: '(inline)')
+      def insert_comments(code, strategy: nil, rewrite: nil, merge: nil, **options)
         strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)
 
-        rewrite_with_report(
-          code,
-          strategy: strategy,
-          config: config,
-          file: file
-        )[:output]
+        rewrite_with_report(code, strategy: strategy, **options)[:output]
       end
 
-      # Rewrite source and return both output and structured change information.
-      #
-      # The result hash includes:
-      # - `:output`  => rewritten source
-      # - `:changes` => structured change records used by CLI explanation output
+      # Rewrite with report
       #
       # @param [String] code Ruby source
-      # @param [Symbol, nil] strategy :safe or :aggressive
-      # @param [Boolean, nil] rewrite compatibility alias for aggressive strategy
-      # @param [Boolean, nil] merge compatibility alias for safe strategy
-      # @param [Docscribe::Config] config config object (defaults to loaded config)
-      # @param [String] file source name used for parser locations/debugging
-      # @param [nil] core_rbs_provider Param documentation.
-      # @raise [Docscribe::ParseError]
-      # @raise [StandardError]
-      # @return [Hash]
-      def rewrite_with_report(code, strategy: nil, rewrite: nil, merge: nil, config: nil,
-                              core_rbs_provider: nil, file: '(inline)')
+      # @param [Symbol?] strategy :safe or :aggressive
+      # @param [Boolean?] rewrite compatibility alias for aggressive strategy
+      # @param [Boolean?] merge compatibility alias for safe strategy
+      # @param [Object] options additional keyword arguments forwarded to downstream helpers
+      # @return [Hash<Symbol, String, Array<Hash<Symbol, Object>>>]
+      def rewrite_with_report(code, strategy: nil, rewrite: nil, merge: nil, **options)
         strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)
         validate_strategy!(strategy)
+        parsed = setup_rewrite_env(code, options)
+        pipeline = build_rewrite_pipeline(parsed[:buffer], parsed[:ast])
+        dispatch_rewrite_insertions(pipeline, parsed[:buffer],
+                                    config: parsed[:config], signature_provider: parsed[:signature_provider],
+                                    core_rbs_provider: parsed[:core_rbs_provider], strategy: strategy,
+                                    file: parsed[:file])
+        { output: pipeline[:rewriter].process, changes: pipeline[:changes] }
+      end
 
-        buffer = Parser::Source::Buffer.new(file.to_s, source: code)
-        ast = Docscribe::Parsing.parse_buffer(buffer)
-        raise Docscribe::ParseError, "Failed to parse #{file}" unless ast
+      # Build rewrite pipeline
+      #
+      # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
+      # @param [Parser::AST::Node] ast the parsed AST of the source code
+      # @return [Hash<Symbol, Object>]
+      def build_rewrite_pipeline(buffer, ast)
+        all = collect_insertions(buffer, ast)
+        method_overrides_by_pos = {} #: Hash[Integer, untyped]
+        all = deduplicate_insertions(all, method_overrides_by_pos: method_overrides_by_pos)
+        rewriter = Parser::Source::TreeRewriter.new(buffer) # steep:ignore
+        merge_inserts = Hash.new { |h, k| h[k] = [] } #: Hash[Integer, untyped]
+        changes = [] #: Array[untyped]
+
+        { all: all, method_overrides_by_pos: method_overrides_by_pos, rewriter: rewriter,
+          merge_inserts: merge_inserts, changes: changes }
+      end
 
-        config ||= Docscribe::Config.load
-        signature_provider = build_signature_provider(config, code, file.to_s)
-        begin
-          core_rbs_provider ||= config.core_rbs_provider if config.respond_to?(:core_rbs_provider)
-        rescue StandardError => e
-          warn "Docscribe: failed to load core RBS provider: #{e.message}" if ENV['DOCSCRIBE_DEBUG']
-          core_rbs_provider = nil
+      # Dispatch rewrite insertions
+      #
+      # @param [Hash<Symbol, Object>] pipeline the pipeline hash with rewriter, insertions, and tracking state
+      # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
+      # @param [Object] options additional kwargs (config, signature_provider, core_rbs_provider, strategy, file)
+      # @return [void]
+      def dispatch_rewrite_insertions(pipeline, buffer, **options)
+        pipeline[:all].sort_by { |(kind, ins)| plugin_insertion_pos(kind, ins) }
+                      .reverse_each do |kind, ins|
+          method_name = :"dispatch_#{kind}_insertion"
+          send(method_name, ins, pipeline, buffer, **options) if respond_to?(method_name, true)
         end
 
-        collector = Docscribe::InlineRewriter::Collector.new(buffer)
-        collector.process(ast)
+        apply_merge_inserts!(rewriter: pipeline[:rewriter], buffer: buffer, merge_inserts: pipeline[:merge_inserts])
+      end
 
-        # Collect additional insertions from CollectorPlugins
-        plugin_insertions = Docscribe::Plugin.run_collector_plugins(ast, buffer)
+      # Dispatch method insertion
+      #
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] ins the attribute insertion object
+      # @param [Hash<Symbol, Object>] pipeline the pipeline hash with rewriter, insertions, and tracking state
+      # @param [Parser::Source::Buffer] buffer the source buffer
+      # @param [Object] options the full keyword options hash
+      # @return [void]
+      def dispatch_method_insertion(ins, pipeline, buffer, **options)
+        pos = plugin_insertion_pos(:method, ins)
+        method_override = pipeline[:method_overrides_by_pos][pos]
+
+        apply_method_insertion!(
+          rewriter: pipeline[:rewriter], buffer: buffer, insertion: ins,
+          config: options[:config], signature_provider: options[:signature_provider],
+          core_rbs_provider: options[:core_rbs_provider], strategy: options[:strategy],
+          changes: pipeline[:changes], file: options[:file],
+          method_override: method_override
+        )
+      end
 
-        method_insertions = collector.insertions
-        attr_insertions = collector.respond_to?(:attr_insertions) ? collector.attr_insertions : []
+      # Dispatch attr insertion
+      #
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
+      # @param [Hash<Symbol, Object>] pipeline the pipeline hash with rewriter, insertions, and tracking state
+      # @param [Parser::Source::Buffer] buffer the source buffer
+      # @param [Object] options the full keyword options hash
+      # @return [void]
+      def dispatch_attr_insertion(ins, pipeline, buffer, **options)
+        apply_attr_insertion!(
+          rewriter: pipeline[:rewriter], buffer: buffer, insertion: ins,
+          config: options[:config], signature_provider: options[:signature_provider],
+          strategy: options[:strategy], merge_inserts: pipeline[:merge_inserts]
+        )
+      end
 
-        all = method_insertions.map { |i| [:method, i] } +
-              attr_insertions.map { |i| [:attr, i] } +
-              plugin_insertions.map { |i| [:plugin, i] }
+      # Dispatch plugin insertion
+      #
+      # @param [Hash<Symbol, Object>] ins the attribute insertion object
+      # @param [Hash<Symbol, Object>] pipeline the pipeline hash with rewriter, insertions, and tracking state
+      # @param [Parser::Source::Buffer] buffer the source buffer
+      # @param [Object] options the full keyword options hash
+      # @return [void]
+      def dispatch_plugin_insertion(ins, pipeline, buffer, **options)
+        apply_plugin_insertion!(
+          rewriter: pipeline[:rewriter], buffer: buffer, insertion: ins,
+          strategy: options[:strategy], config: options[:config]
+        )
+      end
 
-        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 = []
-
-        all.sort_by { |(kind, ins)| plugin_insertion_pos(kind, ins) }
-           .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,
-              insertion: ins,
-              config: config,
-              signature_provider: signature_provider,
-              core_rbs_provider: core_rbs_provider,
-              strategy: strategy,
-              changes: changes,
-              file: file.to_s,
-              method_override: method_override
-            )
-          when :attr
-            apply_attr_insertion!(
-              rewriter: rewriter,
-              buffer: buffer,
-              insertion: ins,
-              config: config,
-              signature_provider: signature_provider,
-              strategy: strategy,
-              merge_inserts: merge_inserts
-            )
-          when :plugin
-            apply_plugin_insertion!(
-              rewriter: rewriter,
-              buffer: buffer,
-              insertion: ins,
-              strategy: strategy,
-              config: config
-            )
-          end
-        end
+      private
 
-        apply_merge_inserts!(rewriter: rewriter, buffer: buffer, merge_inserts: merge_inserts)
+      # Setup rewrite env
+      #
+      # @private
+      # @param [String] code the Ruby source code string to parse and rewrite
+      # @param [Hash<Symbol, Object>] options hash containing :config, :file, and :core_rbs_provider
+      # @raise [Docscribe::ParseError]
+      # @return [Hash<Symbol, Docscribe::Config, String, Parser::Source::Buffer, Parser::AST::Node, Docscribe::Types::ProviderChain, nil, Object, nil>]
+      def setup_rewrite_env(code, options)
+        config = options[:config] || Docscribe::Config.load
+        file = (options[:file] || '(inline)').to_s
+        core_rbs_provider = options[:core_rbs_provider]
+        buffer = Parser::Source::Buffer.new(file, source: code)
+        ast = Docscribe::Parsing.parse_buffer(buffer)
+        raise Docscribe::ParseError, "Failed to parse #{file}" unless ast
 
-        { output: rewriter.process, changes: changes }
+        { config: config, file: file, buffer: buffer, ast: ast,
+          signature_provider: build_signature_provider(config, code, file),
+          core_rbs_provider: load_core_rbs_provider(config, core_rbs_provider) }
       end
 
-      private
+      # Load core rbs provider
+      #
+      # @private
+      # @param [Docscribe::Config] config the active Docscribe::Config
+      # @param [Object, nil] core_rbs_provider optional externally-provided core RBS provider
+      # @raise [StandardError]
+      # @return [Object, nil] if StandardError
+      # @return [nil] if StandardError
+      def load_core_rbs_provider(config, core_rbs_provider)
+        core_rbs_provider || (config.respond_to?(:core_rbs_provider) ? config.core_rbs_provider : nil)
+      rescue StandardError => e
+        warn "Docscribe: failed to load core RBS provider: #{e.message}" if ENV.fetch('DOCSCRIBE_DEBUG', false)
+        nil
+      end
 
-      # Deduplicate insertions by source position.
+      # Collect insertions
       #
-      # 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 [Parser::Source::Buffer] buffer the source buffer to collect insertions from
+      # @param [Parser::AST::Node] ast the parsed AST to traverse for collection
+      # @return [Array<Object>]
+      def collect_insertions(buffer, ast)
+        collector = Docscribe::InlineRewriter::Collector.new(buffer)
+        collector.process(ast)
+        plugin_insertions = Docscribe::Plugin.run_collector_plugins(ast, buffer)
+        method_insertions = collector.insertions
+        attr_insertions = collector.respond_to?(:attr_insertions) ? collector.attr_insertions : [] #: Array[untyped]
+        method_insertions.map { |i| [:method, i] } +
+          attr_insertions.map { |i| [:attr, i] } +
+          plugin_insertions.map { |i| [:plugin, i] }
+      end
+
+      # Deduplicate insertions
       #
       # @private
-      # @param [Array<Array(Symbol,Object)>] insertions tagged insertion list
-      # @param [nil] method_overrides_by_pos Param documentation.
-      # @return [Array<Array(Symbol,Object)>]
+      # @param [Array<(Symbol, Object)>] insertions insertions to deduplicate
+      # @param [Hash<Integer, Hash<Symbol, Object>>, nil?] method_overrides_by_pos method-level overrides keyed
+      #   by insertion position
+      # @return [Array<(Symbol, Object)>]
       def deduplicate_insertions(insertions, method_overrides_by_pos: nil)
-        groups = {}
+        group_by_position(insertions).each_with_object([]) do |(pos, items), result|
+          process_dedup_group(pos, items, result, method_overrides_by_pos)
+        end
+      end
+
+      # Process dedup group
+      #
+      # @private
+      # @param [Integer] pos the source begin_pos for the group
+      # @param [Array<(Symbol, Object)>] items grouped items to process
+      # @param [Array<(Symbol, Object)>] result accumulated result array
+      # @param [Hash<Integer, Hash<Symbol, Object>>, nil] method_overrides_by_pos hash mapping position to method
+      #   override data
+      # @return [void]
+      def process_dedup_group(pos, items, result, method_overrides_by_pos)
+        plugin_items = items.select { |pair| pair.first == :plugin }
+        return result.concat(items) if plugin_items.empty?
+
+        method_items = items.select { |pair| pair.first == :method }
+        override_items = find_override_items(plugin_items)
+        if override_items.any? && method_items.any?
+          handle_override_case(result, items, override_items, method_overrides_by_pos, pos)
+        else
+          result.concat(deduplicate_items(items, plugin_items, pos, method_items))
+        end
+      end
 
+      # Group by position
+      #
+      # @private
+      # @param [Array<(Symbol, Object)>] insertions insertions to group
+      # @return [Hash<Integer, Array<(Symbol, Object)>>]
+      def group_by_position(insertions)
+        groups = {} #: Hash[Integer, untyped]
         insertions.each do |kind, ins|
           pos = plugin_insertion_pos(kind, ins)
           (groups[pos] ||= []) << [kind, ins]
         end
+        groups
+      end
 
-        result = []
+      # Find override items
+      #
+      # @private
+      # @param [Array<(Symbol, Object)>] plugin_items plugin items to check
+      # @return [Array<(Symbol, Object)>]
+      def find_override_items(plugin_items)
+        plugin_items.select do |_k, ins|
+          ins.is_a?(Hash) && ins[:method_override].is_a?(Hash)
+        end
+      end
 
-        groups.each do |pos, items|
-          # plugin insertions at this pos
-          plugin_items = items.select { |k, _| k == :plugin }
+      # Handle override case
+      #
+      # @private
+      # @param [Array<(Symbol, Object)>] result accumulated result array
+      # @param [Array<(Symbol, Object)>] items all items in group
+      # @param [Array<(Symbol, Object)>] override_items override plugin items
+      # @param [Hash<Integer, Hash<Symbol, Object>>, nil] method_overrides_by_pos hash mapping position to
+      #   method override data
+      # @param [Integer] pos the source position of the conflict
+      # @return [void]
+      def handle_override_case(result, items, override_items, method_overrides_by_pos, pos)
+        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
 
-          # no plugins -> keep as-is
-          if plugin_items.empty?
-            result.concat(items)
-            next
-          end
+        items = items.reject { |k, ins| k == :plugin && ins.is_a?(Hash) && ins.key?(:method_override) }
+        result.concat(items)
+      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
+      # Deduplicate items
+      #
+      # @private
+      # @param [Array<(Symbol, Object)>] items all items in group
+      # @param [Array<(Symbol, Object)>] plugin_items plugin items in group
+      # @param [Integer] pos the source position of the conflict
+      # @param [Array<(Symbol, Object)>] _method_items method items in group
+      # @return [Array<(Symbol, Object)>]
+      def deduplicate_items(items, plugin_items, pos, _method_items)
+        plugin_doc_items = plugin_items.select { |pair| plugin_doc_item?(pair) }
+
+        if plugin_doc_items.any?
+          deduplicate_plugin_doc_case(items, plugin_doc_items, pos)
+        else
+          items.reject { |pair| override_or_plugin_method?(pair) }
+        end
+      end
+
+      # Plugin doc item
+      #
+      # @private
+      # @param [(Symbol, Object)] pair insertion pair to check
+      # @return [Boolean]
+      def plugin_doc_item?(pair)
+        _k, ins = pair
+        ins.is_a?(Hash) && ins[:doc] && !ins[:doc].empty?
+      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
+      # Deduplicate plugin doc case
+      #
+      # @private
+      # @param [Array<(Symbol, Object)>] items all items in group
+      # @param [Array<(Symbol, Object)>] plugin_doc_items plugin doc items
+      # @param [Integer] pos the source position of the conflict
+      # @return [Array<(Symbol, Object)>]
+      def deduplicate_plugin_doc_case(items, plugin_doc_items, pos)
+        items = items.reject { |k, _| k == :method }
+        items = items.reject { |pair| override_or_plugin_method?(pair) }
 
-            # 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) }
+        max_prio = max_plugin_priority(plugin_doc_items)
+        dropped = filter_lower_priority_plugins(items, max_prio)
+        items = items.reject { |k, ins| dropped.include?([k, ins]) }
 
-            result.concat(items)
-            next
-          end
+        warn_plugin_conflict!(dropped, plugin_doc_items, max_prio, pos) if Docscribe::Plugin.debug? && dropped.any?
+
+        items
+      end
+
+      # Override or plugin method
+      #
+      # @private
+      # @param [(Symbol, Object)] pair insertion pair to check
+      # @return [Boolean]
+      def override_or_plugin_method?(pair)
+        k, ins = pair
+        k == :plugin && ins.is_a?(Hash) && ins.key?(:method_override)
+      end
+
+      # Max plugin priority
+      #
+      # @private
+      # @param [Array<(Symbol, Object)>] plugin_items plugin items to scan
+      # @return [Integer]
+      def max_plugin_priority(plugin_items)
+        plugin_items.map { |_k, ins| plugin_insertion_priority(ins) }.max || 0
+      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)
+      # Filter lower priority plugins
+      #
+      # @private
+      # @param [Array<(Symbol, Object)>] items items to filter
+      # @param [Integer] threshold minimum priority threshold
+      # @return [Array<(Symbol, Object)>]
+      def filter_lower_priority_plugins(items, threshold)
+        items.select do |k, ins|
+          k == :plugin && ins.is_a?(Hash) && ins[:doc] && plugin_insertion_priority(ins) < threshold
         end
+      end
 
-        result
+      # Warn plugin conflict
+      #
+      # @private
+      # @param [Array<(Symbol, Object)>] dropped dropped plugin items
+      # @param [Array<(Symbol, Object)>] plugin_items kept plugin items
+      # @param [Integer] max_prio the maximum priority value
+      # @param [Integer] pos the source position of the conflict
+      # @return [void]
+      def warn_plugin_conflict!(dropped, plugin_items, max_prio, pos)
+        kept_labels = plugin_items.map { |_k, ins| plugin_insertion_label(ins) }.uniq
+        dropped_labels = dropped.map { |_k, ins| plugin_insertion_label(ins) }.uniq
+        loc = conflict_location_str(pos, plugin_items)
+        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
 
+      # Conflict location str
+      #
       # @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)
+      # @param [Integer] pos the source position of the conflict
+      # @param [Array<(Symbol, Object)>] plugin_items plugin items for location
+      # @return [String]
+      def conflict_location_str(pos, plugin_items)
+        line = plugin_insertion_line(plugin_items.first[1])
+        "pos=#{pos}#{" line=#{line}" if line}"
+      end
+
+      # Pick highest priority override insertion
+      #
+      # @private
+      # @param [Array<(Symbol, Object)>] override_items override items to prioritize
+      # @param [Integer] pos begin_pos (used only for debug output)
+      # @return [Hash<Symbol, Object>, 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
+        max_prio = max_plugin_priority_for(override_items)
+        winners  = override_items.select { |_k, ins| plugin_insertion_priority(ins) == max_prio }
+        winners_sorted = sort_winners_by_order(winners)
 
-        winners =
-          override_items.select { |_k, ins| plugin_insertion_priority(ins) == max_prio }
+        warn_override_conflict!(winners_sorted, max_prio, pos)
 
-        # 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
+        winners_sorted.first[1]
+      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
+      # Max plugin priority for
+      #
+      # @private
+      # @param [Array<(Symbol, Object)>] override_items override items to evaluate
+      # @return [Integer]
+      def max_plugin_priority_for(override_items)
+        override_items.map { |_k, ins| plugin_insertion_priority(ins) }.max || 0
+      end
+
+      # Sort winners by order
+      #
+      # @private
+      # @param [Array<(Symbol, Object)>] winners winning items to sort
+      # @return [Array<(Symbol, Object)>]
+      def sort_winners_by_order(winners)
+        winners.sort_by do |_k, ins|
+          order = ins.is_a?(Hash) ? ins[:__docscribe_plugin_order] : nil
+          order || 0
         end
+      end
 
-        winners_sorted.first[1]
+      # Warn override conflict
+      #
+      # @private
+      # @param [Array<(Symbol, Object)>] winners_sorted sorted winning items
+      # @param [Integer] max_prio the maximum priority value
+      # @param [Integer] pos the source position of the conflict
+      # @return [void]
+      def warn_override_conflict!(winners_sorted, max_prio, pos)
+        return unless Docscribe::Plugin.debug?
+
+        labels = winners_sorted.map { |_k, ins| plugin_insertion_label(ins) }.uniq
+        return unless 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
 
+      # Plugin insertion priority
+      #
       # @private
-      # @param [Hash] insertion
+      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected method insertion
       # @raise [StandardError]
-      # @return [Integer]
+      # @return [Integer] if StandardError
+      # @return [Integer] if StandardError
       def plugin_insertion_priority(insertion)
         return 0 unless insertion.is_a?(Hash)
 
@@ -306,10 +466,13 @@ module Docscribe
         0
       end
 
+      # Plugin insertion label
+      #
       # @private
-      # @param [Hash] insertion
+      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected method insertion
       # @raise [StandardError]
-      # @return [String]
+      # @return [String] if StandardError
+      # @return [String] if StandardError
       def plugin_insertion_label(insertion)
         return 'unknown' unless insertion.is_a?(Hash)
 
@@ -319,63 +482,74 @@ module Docscribe
         'unknown'
       end
 
+      # Plugin insertion line
+      #
       # @private
-      # @param [Hash] insertion
+      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected method insertion
       # @raise [StandardError]
-      # @return [Integer, nil]
+      # @return [Integer, nil] if StandardError
+      # @return [nil] if StandardError
       def plugin_insertion_line(insertion)
         return nil unless insertion.is_a?(Hash)
 
-        insertion[:anchor_node]&.loc&.expression&.line
+        anchor_node = insertion[:anchor_node]
+        expression = anchor_node&.loc&.expression
+        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).
+      # Plugin insertion pos
       #
       # @private
       # @param [Symbol] kind :method, :attr, or :plugin
-      # @param [Object] ins insertion object or hash
+      # @param [Hash<Symbol, Object>] ins insertion to locate
       # @return [Integer]
       def plugin_insertion_pos(kind, ins)
         case kind
         when :plugin
-          ins[:anchor_node].loc.expression.begin_pos
+          plugin_ins = ins #: Hash[Symbol, untyped]
+          plugin_ins[:anchor_node].loc.expression.begin_pos
         else
-          ins.node.loc.expression.begin_pos
+          method_ins = ins #: Collector::Insertion | Collector::AttrInsertion
+          method_ins.node.loc.expression.begin_pos
         end
       end
 
-      # Apply one CollectorPlugin insertion according to the selected strategy.
-      #
-      # :safe       — skip if a doc-like block already exists above anchor_node
-      # :aggressive — remove existing doc block, insert fresh
+      # Apply plugin insertion
       #
       # @private
-      # @param [Parser::Source::TreeRewriter] rewriter
-      # @param [Parser::Source::Buffer] buffer
-      # @param [Hash] insertion { anchor_node:, doc: }
-      # @param [Symbol] strategy
-      # @param [Docscribe::Config] config
+      # @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
+      # @param [Parser::Source::Buffer] buffer the source buffer
+      # @param [Hash<Symbol, Object>] insertion { anchor_node:, doc: }
+      # @param [Symbol] strategy :safe or :aggressive rewrite mode
+      # @param [Docscribe::Config] config the active configuration
       # @return [void]
       def apply_plugin_insertion!(rewriter:, buffer:, insertion:, strategy:, config:)
-        anchor_node = insertion[:anchor_node]
-        doc         = insertion[:doc]
+        anchor_node, doc = insertion.values_at(:anchor_node, :doc)
         return unless anchor_node && doc && !doc.empty?
 
         indent = SourceHelpers.line_indent(anchor_node)
-        doc    = normalize_plugin_doc(doc, indent, config: config, anchor_node: anchor_node)
+        doc = normalize_plugin_doc(doc, indent, config: config, anchor_node: anchor_node)
         bol_range = SourceHelpers.line_start_range(buffer, anchor_node)
+        insert_plugin_doc(rewriter, buffer, bol_range, doc, strategy)
+      end
 
+      # Insert plugin doc
+      #
+      # @private
+      # @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
+      # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
+      # @param [Parser::Source::Range] bol_range the beginning-of-line range for the anchor node
+      # @param [String] doc the normalized documentation string to insert
+      # @param [Symbol] strategy :safe or :aggressive rewrite mode
+      # @return [void]
+      def insert_plugin_doc(rewriter, buffer, bol_range, doc, strategy)
         case strategy
         when :aggressive
-          # Will remove ANY comments above the method. Plugin will decide what will be changed.
-          if (range = any_comment_block_removal_range(buffer, bol_range.begin_pos))
-            rewriter.remove(range)
-          end
+          range = any_comment_block_removal_range(buffer, bol_range.begin_pos)
+          rewriter.remove(range) if range
           rewriter.insert_before(bol_range, doc)
-
         when :safe
           return if SourceHelpers.already_has_doc_immediately_above?(buffer, bol_range.begin_pos)
 
@@ -383,95 +557,130 @@ module Docscribe
         end
       end
 
-      # Remove any contiguous comment block immediately above anchor_node,
-      # regardless of whether it looks like documentation.
-      #
-      # Used by CollectorPlugin in aggressive mode where the plugin itself
-      # is responsible for deciding what to replace.
+      # Any comment block removal range
       #
       # @private
-      # @param [Parser::Source::Buffer] buffer
+      # @param [Parser::Source::Buffer] buffer the source buffer
       # @param [Integer] bol_pos beginning-of-line position of anchor_node
       # @return [Parser::Source::Range, nil]
       def any_comment_block_removal_range(buffer, bol_pos)
         src   = buffer.source
         lines = src.lines
-        def_line_idx = src[0...bol_pos].count("\n")
-        i = def_line_idx - 1
+        i = nearest_comment_line_index(src, lines, bol_pos)
+        return nil unless i
 
-        # Skip blank lines directly above node
-        i -= 1 while i >= 0 && lines[i].strip.empty?
+        start_idx = comment_block_start_index(lines, i)
 
-        # Nearest non-blank line must be a comment
-        return nil unless i >= 0 && lines[i] =~ /^\s*#/
+        removable_start_idx = skip_preserved_lines(lines, start_idx, i)
+        return nil if removable_start_idx > i
 
-        # Walk upward through the entire contiguous comment block
-        start_idx = i
-        start_idx -= 1 while start_idx >= 0 && lines[start_idx] =~ /^\s*#/
-        start_idx += 1
+        start_pos = removable_start_idx.positive? ? (lines[0...removable_start_idx] || []).join.length : 0
+        Parser::Source::Range.new(buffer, start_pos, bol_pos)
+      end
 
-        # Preserve leading directive-style lines (rubocop, magic comments, etc.)
-        removable_start_idx = start_idx
-        while removable_start_idx <= i &&
-              SourceHelpers.preserved_comment_line?(lines[removable_start_idx])
-          removable_start_idx += 1
-        end
+      # Nearest comment line index
+      #
+      # @private
+      # @param [String] src the full source string of the buffer
+      # @param [Array<String>] lines array of source code lines
+      # @param [Integer] bol_pos character position of the beginning of the anchor line
+      # @return [Integer, nil]
+      def nearest_comment_line_index(src, lines, bol_pos)
+        def_line_idx = (src[0...bol_pos] || '').count("\n")
+        i = def_line_idx - 1
+        i -= 1 while i >= 0 && lines[i].strip.empty?
+        return nil unless i >= 0 && lines[i] =~ /^\s*#/
 
-        return nil if removable_start_idx > i
+        i
+      end
 
-        start_pos = removable_start_idx.positive? ? lines[0...removable_start_idx].join.length : 0
-        Parser::Source::Range.new(buffer, start_pos, bol_pos)
+      # Comment block start index
+      #
+      # @private
+      # @param [Array<String>] lines array of source code lines
+      # @param [Integer] def_line_idx the index in lines of the method definition (anchor) line
+      # @return [Integer]
+      def comment_block_start_index(lines, def_line_idx)
+        start_idx = def_line_idx
+        start_idx -= 1 while start_idx >= 0 && lines[start_idx] =~ /^\s*#/
+        start_idx + 1
       end
 
-      # Normalize a CollectorPlugin-provided doc string before insertion.
+      # Skip preserved lines
       #
-      # 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 [Array<String>] lines array of source code lines
+      # @param [Integer] start_idx index of the first line of the comment block
+      # @param [Integer] def_line_idx the index in lines of the method definition (anchor) line
+      # @return [Integer]
+      def skip_preserved_lines(lines, start_idx, def_line_idx)
+        idx = start_idx
+        idx += 1 while idx <= def_line_idx && SourceHelpers.preserved_comment_line?(lines[idx])
+        idx
+      end
+
+      # Normalize plugin doc
       #
       # @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
+      # @param [String] doc Raw doc string returned by a CollectorPlugin insertion (`:doc`)
+      # @param [String] indent Indentation to apply to every doc line
+      # @param [Docscribe::Config] config Effective Docscribe config for this run
+      # @param [Parser::AST::Node, nil] anchor_node 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)
+        doc = trim_trailing_blank_lines(doc)
+        if anchor_node && %i[def defs].include?(anchor_node.type) && config.include_default_message?
+          doc = prepend_default_message_if_no_prose(doc, anchor_node, indent, config)
+        end
+        doc
+      end
 
+      # Trim trailing blank lines
+      #
+      # @private
+      # @param [String] doc the documentation string to trim
+      # @return [String]
+      def trim_trailing_blank_lines(doc)
         lines = doc.lines
         lines.pop while lines.any? && lines.last.strip.empty?
+        result = lines.join
+        result.end_with?("\n") ? result : "#{result}\n"
+      end
 
-        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
+      # Prepend default message if no prose
+      #
+      # @private
+      # @param [String] doc the plugin-generated documentation string
+      # @param [Parser::AST::Node] anchor_node the AST node used as the insertion anchor
+      # @param [String] indent whitespace indentation prefix derived from the anchor node
+      # @param [Docscribe::Config] config the active Docscribe::Config
+      # @return [String]
+      def prepend_default_message_if_no_prose(doc, anchor_node, indent, config)
+        return doc if doc_has_prose?(doc)
 
-            true
-          end
+        scope = anchor_node.type == :defs ? :class : :instance
+        msg = config.default_message(scope, :public)
+        "#{indent}# #{msg}\n#{indent}#\n" + doc
+      end
 
-          unless has_prose
-            doc = "#{indent}# #{msg}\n#{indent}#\n" + doc
-          end
+      # Doc has prose
+      #
+      # @private
+      # @param [String] doc the documentation string to inspect
+      # @return [Boolean]
+      def doc_has_prose?(doc)
+        doc.lines.any? do |l|
+          s = l.strip
+          next false if s.empty? || s == '#'
+          next false if s.start_with?('# @')
+          next false if s.start_with?('# +')
+
+          true
         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
-      # and re-prefix it with the indent derived from anchor_node.
+      # Normalize plugin doc indent
       #
       # @private
       # @param [String] doc raw doc string from plugin
@@ -484,18 +693,12 @@ module Docscribe
         end.join
       end
 
-      # Normalize strategy inputs, including compatibility booleans.
-      #
-      # Precedence:
-      # - explicit `strategy`
-      # - `rewrite: true` => `:aggressive`
-      # - `merge: true` => `:safe`
-      # - default => `:safe`
+      # Normalize strategy
       #
       # @private
-      # @param [Symbol, nil] strategy
-      # @param [Boolean, nil] rewrite
-      # @param [Boolean, nil] merge
+      # @param [Symbol, nil] strategy :safe or :aggressive rewrite mode
+      # @param [Boolean, nil] rewrite compatibility alias for aggressive strategy
+      # @param [Boolean, nil] merge compatibility alias for safe strategy
       # @return [Symbol]
       def normalize_strategy(strategy:, rewrite:, merge:)
         return strategy if strategy
@@ -505,10 +708,10 @@ module Docscribe
         :safe
       end
 
-      # Validate a normalized rewrite strategy.
+      # Validate strategy
       #
       # @private
-      # @param [Symbol] strategy
+      # @param [Symbol] strategy :safe or :aggressive rewrite mode
       # @raise [ArgumentError]
       # @return [void]
       def validate_strategy!(strategy)
@@ -517,474 +720,711 @@ module Docscribe
         raise ArgumentError, "Unknown strategy: #{strategy.inspect}"
       end
 
-      # Apply one method insertion according to the selected strategy.
+      # Apply method insertion
       #
-      # Safe strategy:
-      # - merge into existing doc-like blocks when present
-      # - otherwise insert a full doc block non-destructively
+      # @private
+      # @param [Object] options kwargs with insertion, config, rewriter, buffer, strategy, changes, file, doc params
+      # @return [void]
+      def apply_method_insertion!(**options)
+        insertion = options[:insertion]
+        config = options[:config]
+        return unless method_insertion_allowed?(insertion, config)
+
+        anchor_bol_range, = method_bol_ranges(options[:buffer], insertion)
+        params = build_method_insertion_params(insertion, config, options[:signature_provider],
+                                               options[:core_rbs_provider], options[:method_override])
+        extract_existing_descriptions!(options[:buffer], insertion, params, options[:strategy], config)
+        doc = DocBuilder.build(insertion, **params) # steep:ignore
+        dispatch_method_insertion_by_strategy!(anchor_bol_range, options, params, doc)
+      end
+
+      # Dispatch method insertion by strategy
+      #
+      # @private
+      # @param [Parser::Source::Range] anchor_bol_range the beginning-of-line range for the anchor node
+      # @param [Hash<Symbol, Object>] options the full keyword options hash passed to apply_method_insertion!
+      # @param [Hash<Symbol, Object>] params precomputed insertion parameters (types, overrides, config)
+      # @param [String, nil] doc the generated documentation block string
+      # @return [void]
+      def dispatch_method_insertion_by_strategy!(anchor_bol_range, options, params, doc)
+        base = { anchor_bol_range: anchor_bol_range, insertion: options[:insertion],
+                 rewriter: options[:rewriter], buffer: options[:buffer],
+                 changes: options[:changes], file: options[:file] }
+        case options[:strategy]
+        when :aggressive then apply_method_insertion_aggressive!(**base, doc: doc)
+        when :safe then apply_method_insertion_safe!(**base, strategy: options[:strategy], **params)
+        end
+      end
+
+      # Method insertion allowed
       #
-      # Aggressive strategy:
-      # - remove the existing doc block (if any)
-      # - insert a fresh regenerated block
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
+      # @param [Docscribe::Config] config the active configuration
+      # @return [Boolean] true if insertion should proceed
+      def method_insertion_allowed?(insertion, config)
+        name = SourceHelpers.node_name(insertion.node) #: Symbol
+        config.process_method?(container: insertion.container, scope: insertion.scope,
+                               visibility: insertion.visibility || :public, name: name)
+      end
+
+      # Extract existing descriptions
       #
       # @private
-      # @param [Parser::Source::TreeRewriter] rewriter
-      # @param [Parser::Source::Buffer] buffer
-      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion
-      # @param [Docscribe::Config] config
-      # @param [Object, nil] signature_provider
-      # @param [Symbol] strategy
-      # @param [Array<Hash>] changes structured change records
-      # @param [String] file
-      # @param [Object] core_rbs_provider Param documentation.
-      # @param [nil] method_override Param documentation.
+      # @param [Parser::Source::Buffer] buffer the source buffer
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
+      # @param [Hash<Symbol, Object>] params precomputed attribute insertion parameters
+      # @param [Symbol] strategy :safe or :aggressive rewrite mode
+      # @param [Docscribe::Config] config the active configuration
       # @return [void]
-      def apply_method_insertion!(rewriter:, buffer:, insertion:, config:, signature_provider:, core_rbs_provider:,
-                                  strategy:, changes:, file:, method_override: nil)
-        name = SourceHelpers.node_name(insertion.node)
+      def extract_existing_descriptions!(buffer, insertion, params, strategy, config)
+        return unless strategy == :aggressive && config.keep_descriptions?
 
-        return unless config.process_method?(
-          container: insertion.container,
-          scope: insertion.scope,
-          visibility: insertion.visibility,
-          name: name
+        parsed = DocBuilder.parse_existing_doc_tags(
+          method_doc_comment_info(buffer, insertion)&.dig(:doc_lines) || []
         )
+        merge_existing_descriptions!(params, parsed)
+      end
 
-        anchor_bol_range, = method_bol_ranges(buffer, insertion)
+      # Merge parsed descriptions into insertion params
+      #
+      # @private
+      # @param [Hash<Symbol, Object>] params insertion params
+      # @param [Hash<Symbol, Object>] parsed parsed tag info
+      # @return [void]
+      def merge_existing_descriptions!(params, parsed)
+        params[:param_descriptions] = parsed[:param_descriptions] if parsed[:param_descriptions].any?
+        params[:return_description] = parsed[:return_description] if parsed[:return_description]
+        params[:description] = parsed[:description] if parsed[:description].any?
+      end
+
+      # Build method insertion params
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
+      # @param [Docscribe::Config] config the active configuration
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider RBS signature provider
+      # @param [Object, nil] core_rbs_provider optional externally-provided core RBS provider
+      # @param [Hash<Symbol, Object>, nil] method_override the raw override data
+      # @return [Hash<Symbol, Object>]
+      def build_method_insertion_params(insertion, config, signature_provider, core_rbs_provider, method_override)
+        override = extract_method_override!(method_override)
+        effective = build_effective_params(insertion, config: config, signature_provider: signature_provider,
+                                                      core_rbs_provider: core_rbs_provider, override: override)
+        { **effective, config: config, signature_provider: signature_provider,
+                       core_rbs_provider: core_rbs_provider }
+      end
+
+      # Build effective params
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
+      # @param [Object] options keyword options
+      # @return [Hash<Symbol, Hash<String, String>, nil, String, nil, Array<Docscribe::Plugin::Tag>>]
+      def build_effective_params(insertion, **options)
+        external_sig = resolve_external_signature(insertion, options[:signature_provider])
+        param_types = resolve_param_types(insertion, external_sig, options[:config])
+        override = options[:override]
+
+        param_types = (param_types || {}).merge(override[:param_types]) if override[:param_types]&.any?
+
+        { param_types: param_types, return_type_override: override[:return_type], override_tags: override[:tags] }
+      end
 
-        # Create external_sig for param_types lookup
-        external_sig = signature_provider&.signature_for(
+      # Resolve external signature
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
+      # @return [Docscribe::Types::MethodSignature, nil]
+      def resolve_external_signature(insertion, signature_provider)
+        node_name = SourceHelpers.node_name(insertion.node) #: Symbol
+        signature_provider&.signature_for(
           container: insertion.container,
           scope: insertion.scope,
-          name: SourceHelpers.node_name(insertion.node)
+          name: node_name
         )
-        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
-          if (range = method_comment_block_removal_range(buffer, insertion))
-            rewriter.remove(range)
-          end
+      end
 
-          effective_param_types = external_sig&.param_types || DocBuilder.build_param_types_from_node(
-            insertion.node,
-            external_sig: external_sig,
-            config: config
+      # Resolve param types
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
+      # @param [Docscribe::Types::MethodSignature, nil] external_sig the resolved signature from the signature provider
+      # @param [Docscribe::Config] config the active Docscribe::Config
+      # @return [Hash<String, String>, nil]
+      def resolve_param_types(insertion, external_sig, config)
+        if external_sig
+          DocBuilder.build_param_types_from_node(
+            insertion.node, external_sig: external_sig, config: config
           )
+        else
+          DocBuilder.build_param_types_from_node(
+            insertion.node, external_sig: nil, config: config
+          )
+        end
+      end
 
-          if override_param_types && !override_param_types.empty?
-            effective_param_types = effective_param_types.merge(override_param_types)
-          end
+      # Apply method insertion aggressive
+      #
+      # @private
+      # @param [Object] options keyword options
+      # @return [void]
+      def apply_method_insertion_aggressive!(**options)
+        rewriter = options[:rewriter]
+        buffer = options[:buffer]
+        insertion = options[:insertion]
+        doc = options[:doc]
+
+        remove_method_comment_block(rewriter, buffer, insertion)
+        return if doc.nil? || doc.empty?
+
+        rewriter.insert_before(options[:anchor_bol_range], doc)
+        add_change(changes: options[:changes], type: :insert_full_doc_block,
+                   insertion: insertion, file: options[:file], message: 'missing docs')
+      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
-          )
+      # Remove method comment block
+      #
+      # @private
+      # @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
+      # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
+      # @return [void]
+      def remove_method_comment_block(rewriter, buffer, insertion)
+        range = method_comment_block_removal_range(buffer, insertion)
+        rewriter.remove(range) if range
+      end
 
-          return if doc.nil? || doc.empty?
+      # Apply method insertion safe
+      #
+      # @private
+      # @param [Object] options keyword options
+      # @return [void]
+      def apply_method_insertion_safe!(**options)
+        info = method_doc_comment_info(options[:buffer], options[:insertion])
 
-          rewriter.insert_before(anchor_bol_range, doc)
+        if info
+          apply_method_insertion_safe_with_info!(**options, info: info)
+        else
+          apply_method_insertion_safe_without_info!(**options)
+        end
+      end
 
-          add_change(
-            changes,
-            type: :insert_full_doc_block,
-            insertion: insertion,
-            file: file,
-            message: 'missing docs'
-          )
+      # Apply method insertion safe with info
+      #
+      # @private
+      # @param [Object] options keyword options
+      # @return [void]
+      def apply_method_insertion_safe_with_info!(**options)
+        i = options[:info]
+        dp = filter_doc_params(options)
+        mr = DocBuilder.build_missing_merge_result( # steep:ignore
+          options[:insertion], existing_lines: i[:doc_lines], strategy: options[:strategy], **dp
+        )
+        changed, n, ob = compute_doc_replacement(i, mr[:lines], strategy: options[:strategy], **dp)
+        commit_safe_doc_outcome(options[:rewriter], options[:buffer], i, n,
+                                old_block: ob, merge_result: mr, existing_order_changed: changed,
+                                insertion: options[:insertion], changes: options[:changes], file: options[:file])
+      end
 
-        when :safe
-          info = method_doc_comment_info(buffer, insertion)
+      # Commit safe doc outcome
+      #
+      # @private
+      # @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
+      # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
+      # @param [Hash<Symbol, Object>] info hash containing existing doc comment block data
+      # @param [String] new_block the newly constructed replacement doc block string
+      # @param [Object] rest additional kwargs (old_block, merge_result,
+      # @return [void]
+      def commit_safe_doc_outcome(rewriter, buffer, info, new_block, **rest)
+        handle_doc_replacement(rewriter, buffer, info, new_block,
+                               insertion: rest[:insertion], changes: rest[:changes],
+                               file: rest[:file],
+                               existing_order_changed: rest[:existing_order_changed])
+        log_method_doc_changes!(insertion: rest[:insertion], merge_result: rest[:merge_result],
+                                new_block: new_block, old_block: rest[:old_block],
+                                changes: rest[:changes], file: rest[:file])
+      end
 
-          effective_param_types = external_sig&.param_types || DocBuilder.build_param_types_from_node(
-            insertion.node,
-            external_sig: external_sig,
-            config: config
-          )
+      # Filter doc params
+      #
+      # @private
+      # @param [Hash<Symbol, Object>] options the full options hash to filter
+      # @return [Hash<Symbol, Object>]
+      def filter_doc_params(options)
+        options.reject { |k, _| %i[rewriter buffer insertion anchor_bol_range info changes file strategy].include?(k) }
+      end
 
-          if override_param_types && !override_param_types.empty?
-            effective_param_types = effective_param_types.merge(override_param_types)
-          end
+      # Handle doc replacement
+      #
+      # @private
+      # @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
+      # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
+      # @param [Hash<Symbol, Object>] info hash containing existing doc comment block data (start_pos, end_pos, lines)
+      # @param [String] new_block the newly constructed replacement doc block string
+      # @param [Object] log_opts additional keyword arguments for logging and recording changes
+      # @return [void]
+      def handle_doc_replacement(rewriter, buffer, info, new_block, **log_opts)
+        range = Parser::Source::Range.new(buffer, info[:start_pos], info[:end_pos])
+        rewriter.replace(range, new_block)
 
-          if info
-            merge_result = build_missing_method_merge_result(
-              insertion,
-              existing_lines: info[:doc_lines],
-              config: config,
-              signature_provider: signature_provider,
-              core_rbs_provider: core_rbs_provider,
-              param_types: effective_param_types,
-              strategy: strategy,
-              return_type_override: override_return_type,
-              override_tags: override_tags
-            )
-
-            missing_lines = merge_result[:lines]
-            reason_specs = merge_result[:reasons] || []
-
-            sorted_existing_doc_lines = Docscribe::InlineRewriter::DocBlock.merge(
-              info[:doc_lines],
-              missing_lines: [],
-              sort_tags: config.sort_tags?,
-              tag_order: config.tag_order
-            )
-
-            merged_doc_lines = Docscribe::InlineRewriter::DocBlock.merge(
-              info[:doc_lines],
-              missing_lines: missing_lines,
-              sort_tags: config.sort_tags?,
-              tag_order: config.tag_order
-            )
-
-            existing_order_changed = sorted_existing_doc_lines != info[:doc_lines]
-            new_block = (info[:preserved_lines] + merged_doc_lines).join
-            old_block = info[:lines].join
-
-            if new_block != old_block
-              range = Parser::Source::Range.new(buffer, info[:start_pos], info[:end_pos])
-              rewriter.replace(range, new_block)
-
-              if existing_order_changed
-                add_change(
-                  changes,
-                  type: :unsorted_tags,
-                  insertion: insertion,
-                  file: file,
-                  message: 'unsorted tags'
-                )
-              end
-            end
-
-            type_mismatch_reasons = reason_specs.select { |r| %i[updated_param updated_return].include?(r[:type]) }
-
-            if new_block != old_block || type_mismatch_reasons.any?
-              reason_specs.each do |reason|
-                add_change(
-                  changes,
-                  type: reason[:type],
-                  insertion: insertion,
-                  file: file,
-                  message: reason[:message],
-                  extra: reason[:extra] || {}
-                )
-              end
-            end
-
-            return
-          end
+        return unless log_opts[:existing_order_changed]
 
-          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?
+        add_change(changes: log_opts[:changes], type: :unsorted_tags,
+                   insertion: log_opts[:insertion], file: log_opts[:file],
+                   message: 'unsorted tags')
+      end
+
+      # Compute doc replacement
+      #
+      # @private
+      # @param [Hash<Symbol, Object>] info existing doc info
+      # @param [Array<String>] missing_lines new doc lines to add
+      # @param [Object] options keyword options
+      # @return [(Boolean, String, String)]
+      def compute_doc_replacement(info, missing_lines, **options)
+        dc = options[:config]
+        sorted = Docscribe::InlineRewriter::DocBlock.merge(
+          info[:doc_lines], missing_lines: [], sort_tags: dc.sort_tags?, tag_order: dc.tag_order
+        )
+        merged = Docscribe::InlineRewriter::DocBlock.merge(
+          info[:doc_lines], missing_lines: missing_lines, sort_tags: dc.sort_tags?, tag_order: dc.tag_order
+        )
+        [sorted != info[:doc_lines], (info[:preserved_lines] + merged).join, info[:lines].join]
+      end
 
-          rewriter.insert_before(anchor_bol_range, doc)
+      # Log method doc changes
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
+      # @param [Hash<Symbol, Object>] merge_result merge operation result
+      # @param [Object] rest additional keyword arguments forwarded to add_change
+      # @return [void]
+      def log_method_doc_changes!(insertion:, merge_result:, **rest)
+        reason_specs = merge_result[:reasons] || []
+        type_mismatch_reasons = reason_specs.select { |r| %i[updated_param updated_return].include?(r[:type]) }
 
-          add_change(
-            changes,
-            type: :insert_full_doc_block,
-            insertion: insertion,
-            file: file,
-            message: 'missing docs'
-          )
+        return unless rest[:new_block] != rest[:old_block] || type_mismatch_reasons.any?
+
+        reason_specs.each do |reason|
+          add_change(changes: rest[:changes], type: reason[:type], insertion: insertion,
+                     file: rest[:file], message: reason[:message], extra: reason[:extra] || {})
         end
       end
 
-      # Append a structured change record.
+      # Apply method insertion safe without info
+      #
+      # @private
+      # @param [Object] options keyword options
+      # @return [void]
+      def apply_method_insertion_safe_without_info!(**options)
+        rewriter = options[:rewriter]
+        insertion = options[:insertion]
+        anchor_bol_range = options[:anchor_bol_range]
+        doc = DocBuilder.build(insertion, **options.reject do |k, _|
+          %i[rewriter buffer insertion anchor_bol_range changes file strategy].include?(k)
+        end) # steep:ignore
+        return if doc.nil? || doc.empty?
+
+        rewriter.insert_before(anchor_bol_range, doc)
+        add_change(changes: options[:changes], type: :insert_full_doc_block,
+                   insertion: insertion, file: options[:file], message: 'missing docs')
+      end
+
+      # Filter options to keep only doc-building params for safe-without-info mode.
+      # @private
+      # @param [Object] options the full options hash to filter
+      # @return [Object]
+
+      # Add change
       #
       # @private
-      # @param [Array<Hash>] changes
-      # @param [Symbol] type
-      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion
-      # @param [String] file
-      # @param [String] message
-      # @param [Integer, nil] line
-      # @param [Hash] extra
+      # @param [Object] options kwargs for change record (type, file, line, method, message, insertion, changes, extra)
       # @return [void]
-      def add_change(changes, type:, insertion:, file:, message:, line: nil, extra: {})
+      def add_change(**options)
+        changes = options[:changes]
         changes << {
-          type: type,
-          file: file,
-          line: line || method_line_for(insertion),
-          method: method_id_for(insertion),
-          message: message
-        }.merge(extra)
+          type: options[:type],
+          file: options[:file],
+          line: options[:line] || method_line_for(options[:insertion]),
+          method: method_id_for(options[:insertion]),
+          message: options[:message]
+        }.merge(options[:extra] || {})
       end
 
-      # Build a printable method identifier from a collected insertion.
+      # Method id for
       #
       # @private
-      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
       # @return [String]
       def method_id_for(insertion)
         name = SourceHelpers.node_name(insertion.node)
         "#{insertion.container}#{insertion.scope == :instance ? '#' : '.'}#{name}"
       end
 
-      # Apply one attribute insertion according to the selected strategy.
+      # Apply attr insertion
       #
       # @private
-      # @param [Parser::Source::TreeRewriter] rewriter
-      # @param [Parser::Source::Buffer] buffer
-      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] insertion
-      # @param [Docscribe::Config] config
-      # @param [Object, nil] signature_provider
-      # @param [Symbol] strategy
-      # @param [Hash] merge_inserts
+      # @param [Object] options kwargs (insertion, config, rewriter, buffer, strategy,
       # @return [void]
-      def apply_attr_insertion!(rewriter:, buffer:, insertion:, config:, signature_provider:, strategy:, merge_inserts:)
+      def apply_attr_insertion!(**options)
+        config = options[:config]
         return unless config.respond_to?(:emit_attributes?) && config.emit_attributes?
-        return unless attribute_allowed?(config, insertion)
+        return unless attribute_allowed?(config, options[:insertion])
 
-        bol_range = SourceHelpers.line_start_range(buffer, insertion.node)
+        bol_range = SourceHelpers.line_start_range(options[:buffer], options[:insertion].node)
+        params = attr_insertion_params(options[:insertion], config, options[:signature_provider], bol_range)
+        dispatch_attr_strategy(params, options)
+      end
 
-        case strategy
-        when :aggressive
-          if (range = SourceHelpers.comment_block_removal_range(buffer, bol_range.begin_pos))
-            rewriter.remove(range)
-          end
+      # Attr insertion params
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected attribute insertion
+      # @param [Docscribe::Config] config the active Docscribe::Config
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
+      # @param [Parser::Source::Range] bol_range the beginning-of-line range for the attribute node
+      # @return [Hash<Symbol, Docscribe::InlineRewriter::Collector::AttrInsertion, Docscribe::Config, Docscribe::Types::ProviderChain, nil, Parser::Source::Range>]
+      def attr_insertion_params(insertion, config, signature_provider, bol_range)
+        {
+          insertion: insertion, config: config,
+          signature_provider: signature_provider, bol_range: bol_range
+        }
+      end
 
-          doc = build_attr_doc_for_node(
-            insertion,
-            config: config,
-            signature_provider: signature_provider
-          )
-          return if doc.nil? || doc.empty?
+      # Dispatch attr strategy
+      #
+      # @private
+      # @param [Hash<Symbol, Object>] params precomputed attribute insertion parameters
+      # @param [Hash<Symbol, Object>] options the full keyword options hash
+      # @return [void]
+      def dispatch_attr_strategy(params, options)
+        case options[:strategy]
+        when :aggressive then apply_attr_aggressive!(params, options[:rewriter], options[:buffer])
+        when :safe then apply_attr_safe!(params, options[:merge_inserts], options[:rewriter], options[:buffer])
+        end
+      end
 
-          rewriter.insert_before(bol_range, doc)
+      # Apply attr aggressive
+      #
+      # @private
+      # @param [Hash<Symbol, Object>] params precomputed attribute insertion parameters
+      # @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
+      # @param [Parser::Source::Buffer] buffer the source buffer
+      # @return [void]
+      def apply_attr_aggressive!(params, rewriter, buffer)
+        if (range = SourceHelpers.comment_block_removal_range(buffer, params[:bol_range].begin_pos))
+          rewriter.remove(range)
+        end
 
-        when :safe
-          info = SourceHelpers.doc_comment_block_info(buffer, bol_range.begin_pos)
+        doc = build_attr_doc_for_node(params[:insertion], config: params[:config],
+                                                          signature_provider: params[:signature_provider])
+        return if doc.nil? || doc.empty?
 
-          if info
-            additions = build_attr_merge_additions(
-              insertion,
-              existing_lines: info[:lines],
-              config: config,
-              signature_provider: signature_provider
-            )
+        rewriter.insert_before(params[:bol_range], doc)
+      end
 
-            if additions && !additions.empty?
-              merge_inserts[info[:end_pos]] << [insertion.node.loc.expression.begin_pos, additions]
-            end
+      # Apply attr safe
+      #
+      # @private
+      # @param [Hash<Symbol, Object>] params precomputed attribute insertion parameters
+      # @param [Hash<Integer, Array<(Integer, String)>>] merge_inserts deferred merge inserts
+      # @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
+      # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
+      # @return [void]
+      def apply_attr_safe!(params, merge_inserts, rewriter, buffer)
+        info = SourceHelpers.doc_comment_block_info(buffer, params[:bol_range].begin_pos)
 
-            return
-          end
+        if info
+          merge_attr_additions!(insertion: params[:insertion], info: info, merge_inserts: merge_inserts,
+                                config: params[:config], signature_provider: params[:signature_provider])
+          return
+        end
 
-          doc = build_attr_doc_for_node(
-            insertion,
-            config: config,
-            signature_provider: signature_provider
-          )
-          return if doc.nil? || doc.empty?
+        doc = build_attr_doc_for_node(params[:insertion], config: params[:config],
+                                                          signature_provider: params[:signature_provider])
+        return if doc.nil? || doc.empty?
 
-          rewriter.insert_before(bol_range, doc)
-        end
+        rewriter.insert_before(params[:bol_range], doc)
       end
 
-      # Apply aggregated merge inserts at shared end positions.
+      # Merge attr additions
       #
-      # Used primarily for attribute merge behavior where multiple additions may target the same block end.
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected attribute insertion
+      # @param [Hash<Symbol, Object>] info hash containing existing doc comment block data
+      # @param [Hash<Integer, Array<(Integer, String)>>] merge_inserts deferred merge inserts
+      # @param [Docscribe::Config] config the active Docscribe::Config
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
+      # @return [void]
+      def merge_attr_additions!(insertion:, info:, merge_inserts:, config:, signature_provider:)
+        additions = build_attr_merge_additions(ins: insertion, existing_lines: info[:lines],
+                                               config: config, signature_provider: signature_provider)
+        return unless additions && !additions.empty?
+
+        merge_inserts[info[:end_pos]] << [insertion.node.loc.expression.begin_pos, additions]
+      end
+
+      # Apply merge inserts
       #
       # @private
-      # @param [Parser::Source::TreeRewriter] rewriter
-      # @param [Parser::Source::Buffer] buffer
-      # @param [Hash{Integer=>Array<(Integer,String)>}] merge_inserts
+      # @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
+      # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
+      # @param [Hash<Integer, Array<(Integer, String)>>] merge_inserts deferred merge inserts
       # @return [void]
       def apply_merge_inserts!(rewriter:, buffer:, merge_inserts:)
-        sep_re = /^\s*#\s*\r?\n$/
-
         merge_inserts.keys.sort.reverse_each do |end_pos|
-          chunks = merge_inserts[end_pos]
-          next if chunks.empty?
-
-          chunks = chunks.sort_by { |(sort_key, _s)| sort_key }
-
-          out_lines = []
-
-          chunks.each do |(_k, chunk)|
-            next if chunk.nil? || chunk.empty?
-
-            lines = chunk.lines
-            seps = []
-            seps << lines.shift while !lines.empty? && lines.first.match?(sep_re)
-
-            sep = seps.first
-            out_lines << sep if sep && (out_lines.empty? || !out_lines.last.match?(sep_re))
-            out_lines.concat(lines)
-          end
-
-          text = out_lines.join
-          next if text.empty?
+          text = merge_text_for_pos(merge_inserts[end_pos])
+          next if text.nil? || text.empty?
 
           range = Parser::Source::Range.new(buffer, end_pos, end_pos)
           rewriter.insert_before(range, text)
         end
       end
 
-      # Build plain-text merge additions for an attribute doc block.
+      # Merge text for pos
       #
       # @private
-      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins
-      # @param [Array<String>] existing_lines
-      # @param [Docscribe::Config] config
-      # @param [Object] signature_provider Param documentation.
-      # @raise [StandardError]
+      # @param [Array<(Integer, String)>] chunks merge chunks at position
       # @return [String, nil]
-      def build_attr_merge_additions(ins, existing_lines:, config:, signature_provider:)
-        indent = SourceHelpers.line_indent(ins.node)
-        param_tag_style = config.param_tag_style
-        existing = existing_attr_names(existing_lines)
-        missing = ins.names.reject { |name_sym| existing[name_sym.to_s] }
-        return '' if missing.empty?
+      def merge_text_for_pos(chunks)
+        return nil if chunks.empty?
 
-        lines = []
-        lines << "#{indent}#" if existing_lines.any? && existing_lines.last.strip != '#'
+        chunks = chunks.sort_by { |(sort_key, _s)| sort_key }
+        out_lines = [] #: Array[String]
+        sep_re = /^\s*#\s*\r?\n$/
 
-        missing.each_with_index do |name_sym, idx|
-          attr_name = name_sym.to_s
-          mode = ins.access.to_s
-          attr_type = attribute_type(ins, name_sym, config, signature_provider: signature_provider)
+        chunks.each do |(_k, chunk)|
+          next if chunk.nil? || chunk.empty?
 
-          lines << "#{indent}# @!attribute [#{mode}] #{attr_name}"
+          merge_chunk_into_out(chunk, out_lines, sep_re)
+        end
 
-          if config.emit_visibility_tags?
-            lines << "#{indent}# @private" if ins.visibility == :private
-            lines << "#{indent}# @protected" if ins.visibility == :protected
-          end
+        text = out_lines.join
+        text.empty? ? nil : text
+      end
 
-          lines << "#{indent}#   @return [#{attr_type}]" if %i[r rw].include?(ins.access)
-          if %i[w rw].include?(ins.access)
-            lines << format_attribute_param_tag(indent, 'value', attr_type, style: param_tag_style)
-          end
-          lines << "#{indent}#" if idx < missing.length - 1
-        end
+      # Merge chunk into out
+      #
+      # @private
+      # @param [String] chunk the doc text string to merge
+      # @param [Array<String>] out_lines the accumulated output lines array
+      # @param [Regexp] sep_re regex matching separator comment lines (# followed by newline)
+      # @return [void]
+      def merge_chunk_into_out(chunk, out_lines, sep_re)
+        lines = chunk.lines
+        seps = extract_separators(lines, sep_re)
+        sep = seps.first
+        out_lines << sep if sep && (out_lines.empty? || !out_lines.last.match?(sep_re))
+        out_lines.concat(lines)
+      end
+
+      # Extract separators
+      #
+      # @private
+      # @param [Array<String>] lines array of lines from the chunk
+      # @param [Regexp] sep_re regex matching separator comment lines
+      # @return [Array<String>]
+      def extract_separators(lines, sep_re)
+        seps = [] #: Array[String]
+        seps << lines.shift while !lines.empty? && lines.first.match?(sep_re)
+        seps
+      end
+
+      # Build attr merge additions
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
+      # @param [Array<String>] existing_lines array of existing doc comment lines
+      # @param [Docscribe::Config] config the active Docscribe::Config
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
+      # @raise [StandardError]
+      # @return [String, nil] if StandardError
+      # @return [nil] if StandardError
+      def build_attr_merge_additions(ins:, existing_lines:, config:, signature_provider:)
+        missing = missing_attr_names(ins, existing_lines)
+        return '' if missing.empty?
 
+        indent = SourceHelpers.line_indent(ins.node)
+        lines = [] #: Array[String]
+        lines << "#{indent}#" if existing_lines.any? && existing_lines.last.strip != '#'
+        lines.concat(build_attr_doc_lines(ins, indent: indent, config: config,
+                                               signature_provider: signature_provider, names: missing))
         lines.map { |l| "#{l}\n" }.join
       rescue StandardError
         nil
       end
 
-      # Extract already documented attribute names from existing `@!attribute` lines.
+      # Missing attr names
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
+      # @param [Array<String>] existing_lines array of existing doc comment lines
+      # @return [Array<Symbol>]
+      def missing_attr_names(ins, existing_lines)
+        existing = existing_attr_names(existing_lines)
+        ins.names.reject { |name_sym| existing[name_sym.to_s] }
+      end
+
+      # Existing attr names
       #
       # @private
-      # @param [Array<String>] lines
-      # @return [Hash{String=>Boolean}]
+      # @param [Array<String>] lines array of existing doc comment lines
+      # @return [Hash<String, nil, Boolean>]
       def existing_attr_names(lines)
-        names = {}
+        names = {} #: Hash[String, bool]
 
         Array(lines).each do |line|
           if (m = line.match(/^\s*#\s*@!attribute\b(?:\s+\[[^\]]+\])?\s+(\S+)/))
-            names[m[1]] = true
+            names[m[1].to_s] = true
           end
         end
 
         names
       end
 
-      # Decide whether an attribute macro should be emitted according to method filters.
+      # Attribute allowed
       #
       # @private
-      # @param [Docscribe::Config] config
-      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins
+      # @param [Docscribe::Config] config the active configuration
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
       # @return [Boolean]
       def attribute_allowed?(config, ins)
         ins.names.any? do |name_sym|
-          ok = false
-
-          if %i[r rw].include?(ins.access)
-            ok ||= config.process_method?(
-              container: ins.container,
-              scope: ins.scope,
-              visibility: ins.visibility,
-              name: name_sym
-            )
-          end
+          allowed_for_access?(config, ins, name_sym)
+        end
+      end
 
-          if %i[w rw].include?(ins.access)
-            ok ||= config.process_method?(
-              container: ins.container,
-              scope: ins.scope,
-              visibility: ins.visibility,
-              name: :"#{name_sym}="
-            )
-          end
+      # Allowed for access
+      #
+      # @private
+      # @param [Docscribe::Config] config the active Docscribe::Config
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
+      # @param [Symbol] name_sym the attribute name as a Symbol
+      # @return [Boolean]
+      def allowed_for_access?(config, ins, name_sym)
+        ok = false
+
+        if %i[r rw].include?(ins.access)
+          ok ||= config.process_method?(container: ins.container, scope: ins.scope,
+                                        visibility: ins.visibility, name: name_sym)
+        end
 
-          ok
+        if %i[w rw].include?(ins.access)
+          ok ||= config.process_method?(container: ins.container, scope: ins.scope,
+                                        visibility: ins.visibility, name: :"#{name_sym}=")
         end
+
+        ok
       end
 
-      # Build a full `@!attribute` documentation block for one attribute insertion.
+      # Build attr doc for node
       #
       # @private
-      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins
-      # @param [Docscribe::Config] config
-      # @param [Object] signature_provider Param documentation.
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
+      # @param [Docscribe::Config] config the active Docscribe::Config
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
       # @raise [StandardError]
-      # @return [String, nil]
+      # @return [String, nil] if StandardError
+      # @return [nil] if StandardError
       def build_attr_doc_for_node(ins, config:, signature_provider:)
         indent = SourceHelpers.line_indent(ins.node)
-        param_tag_style = config.param_tag_style
-        lines = []
+        lines = build_attr_doc_lines(ins, indent: indent, config: config, signature_provider: signature_provider)
+        lines.map { |l| "#{l}\n" }.join
+      rescue StandardError
+        nil
+      end
 
-        ins.names.each_with_index do |name_sym, idx|
-          attr_name = name_sym.to_s
-          mode = ins.access.to_s
-          attr_type = attribute_type(ins, name_sym, config, signature_provider: signature_provider)
+      # Build attr doc lines
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
+      # @param [String] indent whitespace indentation prefix derived from the attribute node
+      # @param [Docscribe::Config] config the active Docscribe::Config
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
+      # @param [Array<Symbol>, nil?] names optional subset of attribute names to document (defaults to all names)
+      # @return [Array<String>]
+      def build_attr_doc_lines(ins, indent:, config:, signature_provider:, names: nil)
+        names ||= ins.names
+        lines = [] #: Array[untyped]
+
+        names.each_with_index do |name_sym, idx|
+          lines.concat(build_single_attr_lines(ins, name_sym, indent: indent,
+                                                              config: config, signature_provider: signature_provider,
+                                                              idx: idx, total: names.length))
+        end
 
-          lines << "#{indent}# @!attribute [#{mode}] #{attr_name}"
+        lines
+      end
 
-          if config.emit_visibility_tags?
-            lines << "#{indent}# @private" if ins.visibility == :private
-            lines << "#{indent}# @protected" if ins.visibility == :protected
-          end
+      # Build single attr lines
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
+      # @param [Symbol] name_sym the attribute name as a Symbol
+      # @param [String] indent whitespace indentation prefix
+      # @param [Object] opts additional keyword arguments forwarded from build_attr_doc_lines
+      # @return [Array<String>]
+      def build_single_attr_lines(ins, name_sym, indent:, **opts)
+        cfg = opts[:config]
+        attr_type = attribute_type(ins, name_sym, cfg, signature_provider: opts[:signature_provider])
+        lines = ["#{indent}# @!attribute [#{ins.access}] #{name_sym}"]
+        lines.concat(attr_visibility_lines(indent, cfg, ins))
+        append_attr_return_tag(lines, indent, attr_type, ins.access)
+        append_attr_param_tag(lines, indent, attr_type, ins.access, cfg)
+        lines << "#{indent}#" if opts[:idx] < opts[:total] - 1
+        lines
+      end
 
-          lines << "#{indent}#   @return [#{attr_type}]" if %i[r rw].include?(ins.access)
-          if %i[w rw].include?(ins.access)
-            lines << format_attribute_param_tag(indent, 'value', attr_type, style: param_tag_style)
-          end
+      # Append attr return tag
+      #
+      # @private
+      # @param [Array<String>] lines the doc lines array being built
+      # @param [String] indent whitespace indentation prefix
+      # @param [String] attr_type the resolved type string for the attribute
+      # @param [Symbol] access the access level (:r, :w, or :rw)
+      # @return [void]
+      def append_attr_return_tag(lines, indent, attr_type, access)
+        lines << "#{indent}#   @return [#{attr_type}]" if %i[r rw].include?(access)
+      end
 
-          lines << "#{indent}#" if idx < ins.names.length - 1
-        end
+      # Append attr param tag
+      #
+      # @private
+      # @param [Array<String>] lines the doc lines array being built
+      # @param [String] indent whitespace indentation prefix
+      # @param [String] attr_type the resolved type string for the attribute
+      # @param [Symbol] access the access level (:r, :w, or :rw)
+      # @param [Docscribe::Config] cfg the active Docscribe::Config
+      # @return [void]
+      def append_attr_param_tag(lines, indent, attr_type, access, cfg)
+        return unless %i[w rw].include?(access)
 
-        lines.map { |l| "#{l}\n" }.join
-      rescue StandardError
-        nil
+        lines << format_attribute_param_tag(indent, 'value', attr_type, style: cfg.param_tag_style)
+      end
+
+      # Attr visibility lines
+      #
+      # @private
+      # @param [String] indent whitespace indentation prefix
+      # @param [Docscribe::Config] config the active Docscribe::Config
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
+      # @return [Array<String>]
+      def attr_visibility_lines(indent, config, ins)
+        return [] unless config.emit_visibility_tags?
+
+        lines = [] #: Array[String]
+        lines << "#{indent}# @private" if ins.visibility == :private
+        lines << "#{indent}# @protected" if ins.visibility == :protected
+        lines
       end
 
-      # Format an attribute `@param` tag line using the configured param tag style.
+      # Format attribute param tag
       #
       # @private
       # @param [String] indent leading whitespace
-      # @param [Symbol] name attribute name
+      # @param [String] name attribute name
       # @param [String] type attribute type
       # @param [String, Symbol] style param tag style (`"name_type"` or `"type_name"`)
       # @return [String] formatted doc line
@@ -999,17 +1439,16 @@ module Docscribe
         end
       end
 
-      # Determine the attribute type for one attr name.
-      #
-      # Prefers the RBS reader signature when available; otherwise falls back to the config fallback type.
+      # Attribute type
       #
       # @private
-      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins
-      # @param [Symbol] name_sym
-      # @param [Docscribe::Config] config
-      # @param [Object] signature_provider Param documentation.
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
+      # @param [Symbol] name_sym the attribute name as a Symbol
+      # @param [Docscribe::Config] config the active configuration
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider RBS signature provider
       # @raise [StandardError]
-      # @return [String]
+      # @return [String] if StandardError
+      # @return [Object] if StandardError
       def attribute_type(ins, name_sym, config, signature_provider:)
         ty = config.fallback_type
         return ty unless signature_provider
@@ -1020,21 +1459,20 @@ module Docscribe
         config.fallback_type
       end
 
-      # Build the appropriate external signature provider for the given source.
-      #
-      # Checks config methods in order: `signature_provider_for`, `signature_provider`, `rbs_provider`.
+      # Build signature provider
       #
       # @private
       # @param [Docscribe::Config] config the active configuration
       # @param [String] code the source code being processed
       # @param [String] file the file name
       # @raise [StandardError]
-      # @return [Object, nil] a signature provider or nil
+      # @return [Object, nil] if StandardError
+      # @return [Object?] if StandardError
       def build_signature_provider(config, code, file)
         if config.respond_to?(:signature_provider_for)
           config.signature_provider_for(source: code, file: file)
         elsif config.respond_to?(:signature_provider)
-          config.signature_provider
+          config.signature_provider # steep:ignore
         elsif config.respond_to?(:rbs_provider)
           config.rbs_provider
         end
@@ -1042,64 +1480,12 @@ module Docscribe
         config.respond_to?(:rbs_provider) ? config.rbs_provider : nil
       end
 
-      # Delegate to DocBuilder.build for generating a complete doc block.
-      #
-      # @private
-      # @param [Collector::Insertion] insertion the collected method insertion
-      # @param [Docscribe::Config] config the active configuration
-      # @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:, return_type_override:,
-                           override_tags:)
-        DocBuilder.build(
-          insertion,
-          config: config,
-          signature_provider: signature_provider,
-          core_rbs_provider: core_rbs_provider,
-          param_types: param_types,
-          return_type_override: return_type_override,
-          override_tags: override_tags
-        )
-      end
-
-      # Delegate to DocBuilder.build_missing_merge_result for generating missing doc lines only.
-      #
-      # @private
-      # @param [Collector::Insertion] insertion the collected method insertion
-      # @param [Array<String>] existing_lines existing doc-like lines
-      # @param [Docscribe::Config] config the active configuration
-      # @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] 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:, return_type_override:, override_tags: nil)
-        DocBuilder.build_missing_merge_result(
-          insertion,
-          existing_lines: existing_lines,
-          config: config,
-          signature_provider: signature_provider,
-          core_rbs_provider: core_rbs_provider,
-          param_types: param_types,
-          strategy: strategy,
-          return_type_override: return_type_override,
-          override_tags: override_tags
-        )
-      end
-
-      # Get doc comment block info (preceding comments) for a method insertion.
+      # Method doc comment info
       #
       # @private
       # @param [Parser::Source::Buffer] buffer the source buffer
-      # @param [Collector::Insertion] insertion the collected method insertion
-      # @return [Hash, nil] doc comment block info or nil
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
+      # @return [Hash<Symbol, Object>, nil] doc comment block info or nil
       def method_doc_comment_info(buffer, insertion)
         anchor_bol_range, def_bol_range = method_bol_ranges(buffer, insertion)
 
@@ -1107,11 +1493,11 @@ module Docscribe
           SourceHelpers.doc_comment_block_info(buffer, def_bol_range.begin_pos)
       end
 
-      # Find the range of an existing doc comment block to remove (aggressive mode).
+      # Method comment block removal range
       #
       # @private
       # @param [Parser::Source::Buffer] buffer the source buffer
-      # @param [Collector::Insertion] insertion the collected method insertion
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
       # @return [Parser::Source::Range, nil]
       def method_comment_block_removal_range(buffer, insertion)
         anchor_bol_range, def_bol_range = method_bol_ranges(buffer, insertion)
@@ -1120,12 +1506,12 @@ module Docscribe
           SourceHelpers.comment_block_removal_range(buffer, def_bol_range.begin_pos)
       end
 
-      # Get the beginning-of-line ranges for the anchor and method nodes.
+      # Method bol ranges
       #
       # @private
       # @param [Parser::Source::Buffer] buffer the source buffer
-      # @param [Collector::Insertion] insertion the collected method insertion
-      # @return [Array<Parser::Source::Range>]
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
+      # @return [(Parser::Source::Range, Parser::Source::Range)]
       def method_bol_ranges(buffer, insertion)
         anchor_node = anchor_node_for(insertion)
         [
@@ -1134,22 +1520,23 @@ module Docscribe
         ]
       end
 
-      # Get the source line number for the method's anchor node.
+      # Method line for
       #
       # @private
-      # @param [Collector::Insertion] insertion the collected method insertion
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
       # @raise [StandardError]
-      # @return [Integer] the 1-based line number
+      # @return [Integer] if StandardError
+      # @return [Object] if StandardError
       def method_line_for(insertion)
         anchor_node_for(insertion).loc.expression.line
       rescue StandardError
         insertion.node.loc.expression.line
       end
 
-      # Get the anchor node for an insertion (Sorbet `sig` or the method node itself).
+      # Anchor node for
       #
       # @private
-      # @param [Collector::Insertion] insertion the collected method insertion
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
       # @return [Parser::AST::Node]
       def anchor_node_for(insertion)
         if insertion.respond_to?(:anchor_node) && insertion.anchor_node
@@ -1158,6 +1545,36 @@ module Docscribe
           insertion.node
         end
       end
+
+      # Extract method override
+      #
+      # @private
+      # @param [Hash<Symbol, Object>, nil] method_override the raw override data
+      # @return [Hash<Symbol, Object>] normalized override hash
+      def extract_method_override!(method_override)
+        return {} unless method_override.is_a?(Hash)
+
+        {
+          return_type: method_override[:return_type],
+          param_types: method_override[:param_types].is_a?(Hash) ? method_override[:param_types] : {},
+          tags: normalize_override_tags(method_override[:tags])
+        }
+      end
+
+      # Normalize override tags
+      #
+      # @private
+      # @param [Array<Object>] tags raw tag values
+      # @return [Array<Docscribe::Plugin::Tag>]
+      def normalize_override_tags(tags)
+        Array(tags).filter_map do |tag|
+          case tag
+          when Docscribe::Plugin::Tag then tag
+          when Hash
+            Docscribe::Plugin::Tag.new(**tag.transform_keys(&:to_sym))
+          end
+        end
+      end
     end
   end
 end