docscribe 1.1.0 → 1.2.1

data/lib/docscribe/inline_rewriter.rb

@@ -1,540 +1,711 @@
 # frozen_string_literal: true
 
-require 'racc/parser'
 require 'ast'
 require 'parser/deprecation'
 require 'parser/source/buffer'
 require 'parser/source/range'
 require 'parser/source/tree_rewriter'
-require 'parser/ast/processor'
 
 require 'docscribe/config'
-require 'docscribe/infer'
 require 'docscribe/parsing'
 
+require 'docscribe/inline_rewriter/source_helpers'
+require 'docscribe/inline_rewriter/doc_builder'
+require 'docscribe/inline_rewriter/collector'
+require 'docscribe/inline_rewriter/doc_block'
+
 module Docscribe
+  # Raised when source cannot be parsed before rewriting.
+  class ParseError < StandardError; end
+
+  # Rewrite Ruby source to insert or update inline YARD-style documentation.
+  #
+  # Supported strategies:
+  # - `:safe`
+  #   - insert missing docs
+  #   - merge into existing doc-like blocks
+  #   - normalize configured sortable tags
+  #   - preserve existing prose and directives where possible
+  # - `:aggressive`
+  #   - replace existing doc blocks with freshly generated docs
+  #
+  # Compatibility note:
+  # - `merge: true` maps to `strategy: :safe`
+  # - `rewrite: true` maps to `strategy: :aggressive`
   module InlineRewriter
-    # +Docscribe::InlineRewriter.insert_comments+ -> Object
-    #
-    # Method documentation.
-    #
-    # @param [Object] code Param documentation.
-    # @param [Boolean] rewrite Param documentation.
-    # @param [nil] config Param documentation.
-    # @return [Object]
-    def self.insert_comments(code, rewrite: false, config: nil)
-      buffer = Parser::Source::Buffer.new('(inline)')
-      buffer.source = code
-      ast = Docscribe::Parsing.parse_buffer(buffer)
-      return code unless ast
-
-      config ||= Docscribe::Config.load
-
-      collector = Collector.new(buffer)
-      collector.process(ast)
-
-      rewriter = Parser::Source::TreeRewriter.new(buffer)
-
-      collector.insertions
-               .sort_by { |ins| ins.node.loc.expression.begin_pos }
-               .reverse_each do |ins|
-                 bol_range = line_start_range(buffer, ins.node)
-
-                 if rewrite
-                   # If there is a comment block immediately above, remove it (and its trailing blank lines)
-                   if (range = comment_block_removal_range(buffer, bol_range.begin_pos))
-                     rewriter.remove(range)
-                   end
-                 elsif already_has_doc_immediately_above?(buffer, bol_range.begin_pos)
-                   # Skip if a doc already exists immediately above
-                   next
-                 end
-
-                 doc = build_doc_for_node(buffer, ins, config)
-                 next unless doc && !doc.empty?
-
-                 rewriter.insert_before(bol_range, doc)
+    class << self
+      # Rewrite source and return only the rewritten output string.
+      #
+      # This is the main convenience entry point for library usage.
+      #
+      # @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
+      # @return [String]
+      def insert_comments(code, strategy: nil, rewrite: nil, merge: nil, config: nil, file: '(inline)')
+        strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)
+
+        rewrite_with_report(
+          code,
+          strategy: strategy,
+          config: config,
+          file: file
+        )[:output]
       end
 
-      rewriter.process
-    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
+      #
+      # @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
+      # @raise [Docscribe::ParseError]
+      # @return [Hash]
+      def rewrite_with_report(code, strategy: nil, rewrite: nil, merge: nil, config: nil, file: '(inline)')
+        strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)
+        validate_strategy!(strategy)
+
+        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
+
+        config ||= Docscribe::Config.load
+        signature_provider = build_signature_provider(config, code, file.to_s)
+
+        collector = Docscribe::InlineRewriter::Collector.new(buffer)
+        collector.process(ast)
+
+        method_insertions = collector.insertions
+        attr_insertions = collector.respond_to?(:attr_insertions) ? collector.attr_insertions : []
+
+        all = method_insertions.map { |i| [:method, i] } + attr_insertions.map { |i| [:attr, i] }
+
+        rewriter = Parser::Source::TreeRewriter.new(buffer)
+        merge_inserts = Hash.new { |h, k| h[k] = [] }
+        changes = []
+
+        all.sort_by { |(_kind, ins)| ins.node.loc.expression.begin_pos }
+           .reverse_each do |kind, ins|
+          case kind
+          when :method
+            apply_method_insertion!(
+              rewriter: rewriter,
+              buffer: buffer,
+              insertion: ins,
+              config: config,
+              signature_provider: signature_provider,
+              strategy: strategy,
+              changes: changes,
+              file: file.to_s
+            )
+          when :attr
+            apply_attr_insertion!(
+              rewriter: rewriter,
+              buffer: buffer,
+              insertion: ins,
+              config: config,
+              signature_provider: signature_provider,
+              strategy: strategy,
+              merge_inserts: merge_inserts
+            )
+          end
+        end
 
-    # +Docscribe::InlineRewriter.line_start_range+ -> Range
-    #
-    # Method documentation.
-    #
-    # @param [Object] buffer Param documentation.
-    # @param [Object] node Param documentation.
-    # @return [Range]
-    def self.line_start_range(buffer, node)
-      start_pos = node.loc.expression.begin_pos
-      src = buffer.source
-      bol = src.rindex("\n", start_pos - 1) || -1
-      Parser::Source::Range.new(buffer, bol + 1, bol + 1)
-    end
+        apply_merge_inserts!(rewriter: rewriter, buffer: buffer, merge_inserts: merge_inserts)
 
-    # +Docscribe::InlineRewriter.node_name+ -> Object
-    #
-    # Method documentation.
-    #
-    # @param [Object] node Param documentation.
-    # @return [Object]
-    def self.node_name(node)
-      case node.type
-      when :def
-        node.children[0]
-      when :defs
-        node.children[1] # method name symbol
+        { output: rewriter.process, changes: changes }
       end
-    end
 
-    # +Docscribe::InlineRewriter.comment_block_removal_range+ -> Range
-    #
-    # Method documentation.
-    #
-    # @param [Object] buffer Param documentation.
-    # @param [Object] def_bol_pos Param documentation.
-    # @return [Range]
-    def self.comment_block_removal_range(buffer, def_bol_pos)
-      src = buffer.source
-      lines = src.lines
-      # Find def line index
-      def_line_idx = src[0...def_bol_pos].count("\n")
-      i = def_line_idx - 1
-
-      # Walk up and skip blank lines directly above def
-      i -= 1 while i >= 0 && lines[i].strip.empty?
-      # Now if the nearest non-blank line isn't a comment, nothing to remove
-      return nil unless i >= 0 && lines[i] =~ /^\s*#/
-
-      # Find the start of the contiguous comment block
-      start_idx = i
-      start_idx -= 1 while start_idx >= 0 && lines[start_idx] =~ /^\s*#/
-      start_idx += 1
-
-      # End position is at def_bol_pos; start position is BOL of start_idx
-      # Compute absolute buffer positions
-      # Position of BOL for start_idx:
-      start_pos = 0
-      if start_idx.positive?
-        # Sum lengths of all preceding lines
-        start_pos = lines[0...start_idx].join.length
-      end
+      private
 
-      Parser::Source::Range.new(buffer, start_pos, def_bol_pos)
-    end
+      # Normalize strategy inputs, including compatibility booleans.
+      #
+      # Precedence:
+      # - explicit `strategy`
+      # - `rewrite: true` => `:aggressive`
+      # - `merge: true` => `:safe`
+      # - default => `:safe`
+      #
+      # @private
+      # @param [Symbol, nil] strategy
+      # @param [Boolean, nil] rewrite
+      # @param [Boolean, nil] merge
+      # @return [Symbol]
+      def normalize_strategy(strategy:, rewrite:, merge:)
+        return strategy if strategy
+        return :aggressive if rewrite
+        return :safe if merge
+
+        :safe
+      end
 
-    # +Docscribe::InlineRewriter.already_has_doc_immediately_above?+ -> Object
-    #
-    # Method documentation.
-    #
-    # @param [Object] buffer Param documentation.
-    # @param [Object] insert_pos Param documentation.
-    # @return [Object]
-    def self.already_has_doc_immediately_above?(buffer, insert_pos)
-      src = buffer.source
-      lines = src.lines
-      current_line_index = src[0...insert_pos].count("\n")
-      i = current_line_index - 1
-      i -= 1 while i >= 0 && lines[i].strip.empty?
-      return false if i.negative?
-
-      !!(lines[i] =~ /^\s*#/)
-    end
+      # Validate a normalized rewrite strategy.
+      #
+      # @private
+      # @param [Symbol] strategy
+      # @raise [ArgumentError]
+      # @return [void]
+      def validate_strategy!(strategy)
+        return if %i[safe aggressive].include?(strategy)
 
-    # +Docscribe::InlineRewriter.build_doc_for_node+ -> Object
-    #
-    # Method documentation.
-    #
-    # @param [Object] _buffer Param documentation.
-    # @param [Object] insertion Param documentation.
-    # @param [Object] config Param documentation.
-    # @raise [StandardError]
-    # @return [Object]
-    # @return [nil] if StandardError
-    def self.build_doc_for_node(_buffer, insertion, config)
-      node = insertion.node
-      indent = ' ' * node.loc.expression.column
-
-      name =
-        case node.type
-        when :def then node.children[0]
-        when :defs then node.children[1]
-        end
+        raise ArgumentError, "Unknown strategy: #{strategy.inspect}"
+      end
 
-      scope = insertion.scope
-      visibility = insertion.visibility
+      # Apply one method insertion according to the selected strategy.
+      #
+      # Safe strategy:
+      # - merge into existing doc-like blocks when present
+      # - otherwise insert a full doc block non-destructively
+      #
+      # Aggressive strategy:
+      # - remove the existing doc block (if any)
+      # - insert a fresh regenerated block
+      #
+      # @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
+      # @return [void]
+      def apply_method_insertion!(rewriter:, buffer:, insertion:, config:, signature_provider:, strategy:, changes:,
+                                  file:)
+        name = SourceHelpers.node_name(insertion.node)
+
+        return unless config.process_method?(
+          container: insertion.container,
+          scope: insertion.scope,
+          visibility: insertion.visibility,
+          name: name
+        )
+
+        anchor_bol_range, = method_bol_ranges(buffer, insertion)
+
+        case strategy
+        when :aggressive
+          if (range = method_comment_block_removal_range(buffer, insertion))
+            rewriter.remove(range)
+          end
 
-      method_symbol = scope == :instance ? '#' : '.'
-      container = insertion.container
+          doc = build_method_doc(insertion, config: config, signature_provider: signature_provider)
+          return if doc.nil? || doc.empty?
+
+          rewriter.insert_before(anchor_bol_range, doc)
+
+          add_change(
+            changes,
+            type: :insert_full_doc_block,
+            insertion: insertion,
+            file: file,
+            message: 'missing docs'
+          )
+
+        when :safe
+          info = method_doc_comment_info(buffer, insertion)
+
+          if info
+            merge_result = build_missing_method_merge_result(
+              insertion,
+              existing_lines: info[:doc_lines],
+              config: config,
+              signature_provider: signature_provider
+            )
+
+            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)
+
+              reason_specs.each do |reason|
+                add_change(
+                  changes,
+                  type: reason[:type],
+                  insertion: insertion,
+                  file: file,
+                  message: reason[:message],
+                  extra: reason[:extra] || {}
+                )
+              end
+
+              if existing_order_changed
+                add_change(
+                  changes,
+                  type: :unsorted_tags,
+                  insertion: insertion,
+                  file: file,
+                  message: 'unsorted tags'
+                )
+              end
+            end
 
-      # Params
-      params_block = config.emit_param_tags? ? build_params_block(node, indent) : nil
+            return
+          end
 
-      # Raises (rescue and/or raise calls)
-      raise_types = config.emit_raise_tags? ? Docscribe::Infer.infer_raises_from_node(node) : []
+          doc = build_method_doc(insertion, config: config, signature_provider: signature_provider)
+          return if doc.nil? || doc.empty?
 
-      # Returns: normal + conditional rescue returns
-      spec = Docscribe::Infer.returns_spec_from_node(node)
-      normal_type = spec[:normal]
-      rescue_specs = spec[:rescues]
+          rewriter.insert_before(anchor_bol_range, doc)
 
-      lines = []
-      if config.emit_header?
-        lines << "#{indent}# +#{container}#{method_symbol}#{name}+ -> #{normal_type}"
-        lines << "#{indent}#"
+          add_change(
+            changes,
+            type: :insert_full_doc_block,
+            insertion: insertion,
+            file: file,
+            message: 'missing docs'
+          )
+        end
       end
 
-      # Default doc text (configurable per scope/vis)
-      lines << "#{indent}# #{config.default_message(scope, visibility)}"
-      lines << "#{indent}#"
+      # Append a structured change record.
+      #
+      # @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
+      # @return [void]
+      def add_change(changes, type:, insertion:, file:, message:, line: nil, extra: {})
+        changes << {
+          type: type,
+          file: file,
+          line: line || method_line_for(insertion),
+          method: method_id_for(insertion),
+          message: message
+        }.merge(extra)
+      end
 
-      if config.emit_visibility_tags?
-        case visibility
-        when :private then lines << "#{indent}# @private"
-        when :protected then lines << "#{indent}# @protected"
-        end
+      # Build a printable method identifier from a collected insertion.
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion
+      # @return [String]
+      def method_id_for(insertion)
+        name = SourceHelpers.node_name(insertion.node)
+        "#{insertion.container}#{insertion.scope == :instance ? '#' : '.'}#{name}"
       end
 
-      lines.concat(params_block) if params_block
+      # Apply one attribute insertion according to the selected strategy.
+      #
+      # @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
+      # @return [void]
+      def apply_attr_insertion!(rewriter:, buffer:, insertion:, config:, signature_provider:, strategy:, merge_inserts:)
+        return unless config.respond_to?(:emit_attributes?) && config.emit_attributes?
+        return unless attribute_allowed?(config, insertion)
+
+        bol_range = SourceHelpers.line_start_range(buffer, insertion.node)
+
+        case strategy
+        when :aggressive
+          if (range = SourceHelpers.comment_block_removal_range(buffer, bol_range.begin_pos))
+            rewriter.remove(range)
+          end
 
-      raise_types.each { |rt| lines << "#{indent}# @raise [#{rt}]" } if config.emit_raise_tags?
+          doc = build_attr_doc_for_node(
+            insertion,
+            config: config,
+            signature_provider: signature_provider
+          )
+          return if doc.nil? || doc.empty?
 
-      lines << "#{indent}# @return [#{normal_type}]" if config.emit_return_tag?(scope, visibility)
+          rewriter.insert_before(bol_range, doc)
 
-      if config.emit_rescue_conditional_returns?
-        rescue_specs.each do |(exceptions, rtype)|
-          ex_display = exceptions.join(', ')
-          lines << "#{indent}# @return [#{rtype}] if #{ex_display}"
-        end
-      end
+        when :safe
+          info = SourceHelpers.doc_comment_block_info(buffer, bol_range.begin_pos)
 
-      lines.map { |l| "#{l}\n" }.join
-    rescue StandardError
-      nil
-    end
+          if info
+            additions = build_attr_merge_additions(
+              insertion,
+              existing_lines: info[:lines],
+              config: config,
+              signature_provider: signature_provider
+            )
 
-    # +Docscribe::InlineRewriter.build_params_block+ -> Object?
-    #
-    # Method documentation.
-    #
-    # @param [Object] node Param documentation.
-    # @param [Object] indent Param documentation.
-    # @return [Object?]
-    def self.build_params_block(node, indent)
-      args =
-        case node.type
-        when :def then node.children[1]
-        when :defs then node.children[2] # FIX: args is children[2], not [3]
-        end
-      return nil unless args
-
-      params = []
-      (args.children || []).each do |a|
-        case a.type
-        when :arg
-          name = a.children.first.to_s
-          ty = Infer.infer_param_type(name, nil)
-          params << "#{indent}# @param [#{ty}] #{name} Param documentation."
-        when :optarg
-          name, default = *a
-          ty = Infer.infer_param_type(name.to_s, default&.loc&.expression&.source)
-          params << "#{indent}# @param [#{ty}] #{name} Param documentation."
-        when :kwarg
-          name = "#{a.children.first}:"
-          ty = Infer.infer_param_type(name, nil)
-          pname = name.sub(/:$/, '')
-          params << "#{indent}# @param [#{ty}] #{pname} Param documentation."
-        when :kwoptarg
-          name, default = *a
-          name = "#{name}:"
-          ty = Infer.infer_param_type(name, default&.loc&.expression&.source)
-          pname = name.sub(/:$/, '')
-          params << "#{indent}# @param [#{ty}] #{pname} Param documentation."
-        when :restarg
-          name = "*#{a.children.first}"
-          ty = Infer.infer_param_type(name, nil)
-          pname = a.children.first.to_s
-          params << "#{indent}# @param [#{ty}] #{pname} Param documentation."
-        when :kwrestarg
-          name = "**#{a.children.first || 'kwargs'}"
-          ty = Infer.infer_param_type(name, nil)
-          pname = (a.children.first || 'kwargs').to_s
-          params << "#{indent}# @param [#{ty}] #{pname} Param documentation."
-        when :blockarg
-          name = "&#{a.children.first}"
-          ty = Infer.infer_param_type(name, nil)
-          pname = a.children.first.to_s
-          params << "#{indent}# @param [#{ty}] #{pname} Param documentation."
-        when :forward_arg
-          # Ruby 3 '...' forwarding; skip
-        end
-      end
-      params.empty? ? nil : params
-    end
+            if additions && !additions.empty?
+              merge_inserts[info[:end_pos]] << [insertion.node.loc.expression.begin_pos, additions]
+            end
 
-    class VisibilityCtx
-      attr_accessor :default_instance_vis, :default_class_vis, :inside_sclass
-      attr_reader :explicit_instance, :explicit_class
+            return
+          end
 
-      # +Docscribe::InlineRewriter::VisibilityCtx#initialize+ -> Object
-      #
-      # Method documentation.
-      #
-      # @return [Object]
-      def initialize
-        @default_instance_vis = :public
-        @default_class_vis = :public
-        @explicit_instance = {} # { name_sym => :private|:protected|:public }
-        @explicit_class = {} # { name_sym => :private|:protected|:public }
-        @inside_sclass = false
+          doc = build_attr_doc_for_node(
+            insertion,
+            config: config,
+            signature_provider: signature_provider
+          )
+          return if doc.nil? || doc.empty?
+
+          rewriter.insert_before(bol_range, doc)
+        end
       end
 
-      # +Docscribe::InlineRewriter::VisibilityCtx#dup+ -> Object
+      # Apply aggregated merge inserts at shared end positions.
       #
-      # Method documentation.
+      # Used primarily for attribute merge behavior where multiple additions may target the same block end.
       #
-      # @return [Object]
-      def dup
-        c = VisibilityCtx.new
-        c.default_instance_vis = default_instance_vis
-        c.default_class_vis = default_class_vis
-        c.inside_sclass = inside_sclass
-        c.explicit_instance.merge!(explicit_instance)
-        c.explicit_class.merge!(explicit_class)
-        c
-      end
-    end
+      # @private
+      # @param [Parser::Source::TreeRewriter] rewriter
+      # @param [Parser::Source::Buffer] buffer
+      # @param [Hash{Integer=>Array<(Integer,String)>}] merge_inserts
+      # @return [void]
+      def apply_merge_inserts!(rewriter:, buffer:, merge_inserts:)
+        sep_re = /^\s*#\s*\r?\n$/
 
-    # Walks nodes and records where to insert docstrings
-    class Collector < Parser::AST::Processor
-      Insertion = Struct.new(:node, :scope, :visibility, :container)
+        merge_inserts.keys.sort.reverse_each do |end_pos|
+          chunks = merge_inserts[end_pos]
+          next if chunks.empty?
 
-      attr_reader :insertions
+          chunks = chunks.sort_by { |(sort_key, _s)| sort_key }
 
-      # +Docscribe::InlineRewriter::Collector#initialize+ -> Object
-      #
-      # Method documentation.
-      #
-      # @param [Object] buffer Param documentation.
-      # @return [Object]
-      def initialize(buffer)
-        super()
-        @buffer = buffer
-        @insertions = []
-        @name_stack = [] # e.g., ['Demo']
-      end
+          out_lines = []
 
-      # +Docscribe::InlineRewriter::Collector#on_class+ -> Object
-      #
-      # Method documentation.
-      #
-      # @param [Object] node Param documentation.
-      # @return [Object]
-      def on_class(node)
-        cname_node, _super_node, body = *node
-        @name_stack.push(const_name(cname_node))
-        ctx = VisibilityCtx.new
-        process_body(body, ctx)
-        @name_stack.pop
-        node
+          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?
+
+          range = Parser::Source::Range.new(buffer, end_pos, end_pos)
+          rewriter.insert_before(range, text)
+        end
       end
 
-      # +Docscribe::InlineRewriter::Collector#on_module+ -> Object
+      # Build plain-text merge additions for an attribute doc block.
       #
-      # Method documentation.
-      #
-      # @param [Object] node Param documentation.
-      # @return [Object]
-      def on_module(node)
-        cname_node, body = *node
-        @name_stack.push(const_name(cname_node))
-        ctx = VisibilityCtx.new
-        process_body(body, ctx)
-        @name_stack.pop
-        node
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins
+      # @param [Array<String>] existing_lines
+      # @param [Docscribe::Config] config
+      # @param [Object] signature_provider Param documentation.
+      # @raise [StandardError]
+      # @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?
+
+        lines = []
+        lines << "#{indent}#" if existing_lines.any? && existing_lines.last.strip != '#'
+
+        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)
+
+          lines << "#{indent}# @!attribute [#{mode}] #{attr_name}"
+
+          if config.emit_visibility_tags?
+            lines << "#{indent}# @private" if ins.visibility == :private
+            lines << "#{indent}# @protected" if ins.visibility == :protected
+          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
+
+        lines.map { |l| "#{l}\n" }.join
+      rescue StandardError
+        nil
       end
 
-      # +Docscribe::InlineRewriter::Collector#on_def+ -> Object
+      # Extract already documented attribute names from existing `@!attribute` lines.
       #
-      # Method documentation.
-      #
-      # @param [Object] node Param documentation.
-      # @return [Object]
-      def on_def(node)
-        @insertions << Insertion.new(node, :instance, :public, current_container)
-        node
+      # @private
+      # @param [Array<String>] lines
+      # @return [Hash{String=>Boolean}]
+      def existing_attr_names(lines)
+        names = {}
+
+        Array(lines).each do |line|
+          if (m = line.match(/^\s*#\s*@!attribute\b(?:\s+\[[^\]]+\])?\s+(\S+)/))
+            names[m[1]] = true
+          end
+        end
+
+        names
       end
 
-      # +Docscribe::InlineRewriter::Collector#on_defs+ -> Object
+      # Decide whether an attribute macro should be emitted according to method filters.
       #
-      # Method documentation.
-      #
-      # @param [Object] node Param documentation.
-      # @return [Object]
-      def on_defs(node)
-        @insertions << Insertion.new(node, :class, :public, current_container)
-        node
-      end
+      # @private
+      # @param [Docscribe::Config] config
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins
+      # @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
 
-      private
+          if %i[w rw].include?(ins.access)
+            ok ||= config.process_method?(
+              container: ins.container,
+              scope: ins.scope,
+              visibility: ins.visibility,
+              name: :"#{name_sym}="
+            )
+          end
 
-      # +Docscribe::InlineRewriter::Collector#process_stmt+ -> Object
-      #
-      # Method documentation.
+          ok
+        end
+      end
+
+      # Build a full `@!attribute` documentation block for one attribute insertion.
       #
       # @private
-      # @param [Object] node Param documentation.
-      # @param [Object] ctx Param documentation.
-      # @return [Object]
-      def process_stmt(node, ctx)
-        return unless node
-
-        case node.type
-        when :def
-          name, _args, _body = *node
-          if ctx.inside_sclass
-            vis = ctx.explicit_class[name] || ctx.default_class_vis
-            scope = :class
-          else
-            vis = ctx.explicit_instance[name] || ctx.default_instance_vis
-            scope = :instance
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins
+      # @param [Docscribe::Config] config
+      # @param [Object] signature_provider Param documentation.
+      # @raise [StandardError]
+      # @return [String, nil]
+      def build_attr_doc_for_node(ins, config:, signature_provider:)
+        indent = SourceHelpers.line_indent(ins.node)
+        param_tag_style = config.param_tag_style
+        lines = []
+
+        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)
+
+          lines << "#{indent}# @!attribute [#{mode}] #{attr_name}"
+
+          if config.emit_visibility_tags?
+            lines << "#{indent}# @private" if ins.visibility == :private
+            lines << "#{indent}# @protected" if ins.visibility == :protected
           end
-          @insertions << Insertion.new(node, scope, vis, current_container)
 
-        when :defs
-          _, name, _args, _body = *node
-          vis = ctx.explicit_class[name] || ctx.default_class_vis
-          @insertions << Insertion.new(node, :class, vis, current_container)
+          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
 
-        when :sclass
-          recv, body = *node
-          inner_ctx = ctx.dup
-          inner_ctx.inside_sclass = self_node?(recv)
-          inner_ctx.default_class_vis = :public
-          process_body(body, inner_ctx)
+          lines << "#{indent}#" if idx < ins.names.length - 1
+        end
 
-        when :send
-          process_visibility_send(node, ctx)
+        lines.map { |l| "#{l}\n" }.join
+      rescue StandardError
+        nil
+      end
 
+      # Method documentation.
+      #
+      # @private
+      # @param [Object] indent Param documentation.
+      # @param [Object] name Param documentation.
+      # @param [Object] type Param documentation.
+      # @param [Object] style Param documentation.
+      # @return [String]
+      def format_attribute_param_tag(indent, name, type, style:)
+        type = type.to_s
+
+        case style.to_s
+        when 'name_type'
+          "#{indent}#   @param #{name} [#{type}]"
         else
-          process(node)
+          "#{indent}#   @param [#{type}] #{name}"
         end
       end
 
-      # +Docscribe::InlineRewriter::Collector#process_visibility_send+ -> Object
+      # Determine the attribute type for one attr name.
+      #
+      # Prefers the RBS reader signature when available; otherwise falls back to the config fallback type.
       #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins
+      # @param [Symbol] name_sym
+      # @param [Docscribe::Config] config
+      # @param [Object] signature_provider Param documentation.
+      # @raise [StandardError]
+      # @return [String]
+      def attribute_type(ins, name_sym, config, signature_provider:)
+        ty = config.fallback_type
+        return ty unless signature_provider
+
+        reader_sig = signature_provider.signature_for(container: ins.container, scope: ins.scope, name: name_sym)
+        reader_sig&.return_type || ty
+      rescue StandardError
+        config.fallback_type
+      end
+
       # Method documentation.
       #
       # @private
-      # @param [Object] node Param documentation.
-      # @param [Object] ctx Param documentation.
+      # @param [Object] config Param documentation.
+      # @param [Object] code Param documentation.
+      # @param [Object] file Param documentation.
+      # @raise [StandardError]
       # @return [Object]
-      def process_visibility_send(node, ctx)
-        recv, meth, *args = *node
-        return unless recv.nil? && %i[private protected public].include?(meth)
-
-        if args.empty?
-          # bare keyword: affects current def-target
-          if ctx.inside_sclass
-            ctx.default_class_vis = meth
-          else
-            ctx.default_instance_vis = meth
-          end
-        else
-          # explicit list: affects current def-target
-          args.each do |arg|
-            sym = extract_name_sym(arg)
-            next unless sym
-
-            if ctx.inside_sclass
-              ctx.explicit_class[sym] = meth
-            else
-              ctx.explicit_instance[sym] = meth
-            end
-
-            target = ctx.inside_sclass ? 'class' : 'instance'
-            if args.empty?
-              puts "[vis] bare #{meth} -> default_#{target}_vis=#{meth}"
-            else
-              puts "[vis] explicit #{meth} -> #{target} names=#{args.map { |a| extract_name_sym(a) }.inspect}"
-            end
-          end
+      # @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
+        elsif config.respond_to?(:rbs_provider)
+          config.rbs_provider
         end
+      rescue StandardError
+        config.respond_to?(:rbs_provider) ? config.rbs_provider : nil
       end
 
-      # +Docscribe::InlineRewriter::Collector#extract_name_sym+ -> Object
-      #
       # Method documentation.
       #
       # @private
-      # @param [Object] arg Param documentation.
+      # @param [Object] insertion Param documentation.
+      # @param [Object] config Param documentation.
+      # @param [Object] signature_provider Param documentation.
       # @return [Object]
-      def extract_name_sym(arg)
-        case arg.type
-        when :sym then arg.children.first
-        when :str then arg.children.first.to_sym
-        end
+      def build_method_doc(insertion, config:, signature_provider:)
+        DocBuilder.build(
+          insertion,
+          config: config,
+          signature_provider: signature_provider
+        )
       end
 
-      # +Docscribe::InlineRewriter::Collector#self_node?+ -> Object
-      #
       # Method documentation.
       #
       # @private
-      # @param [Object] node Param documentation.
+      # @param [Object] insertion Param documentation.
+      # @param [Object] existing_lines Param documentation.
+      # @param [Object] config Param documentation.
+      # @param [Object] signature_provider Param documentation.
       # @return [Object]
-      def self_node?(node)
-        node && node.type == :self
+      def build_missing_method_merge_result(insertion, existing_lines:, config:, signature_provider:)
+        DocBuilder.build_missing_merge_result(
+          insertion,
+          existing_lines: existing_lines,
+          config: config,
+          signature_provider: signature_provider
+        )
       end
 
-      # +Docscribe::InlineRewriter::Collector#current_container+ -> Object
-      #
       # Method documentation.
       #
       # @private
+      # @param [Object] buffer Param documentation.
+      # @param [Object] insertion Param documentation.
       # @return [Object]
-      def current_container
-        @name_stack.empty? ? 'Object' : @name_stack.join('::')
+      def method_doc_comment_info(buffer, insertion)
+        anchor_bol_range, def_bol_range = method_bol_ranges(buffer, insertion)
+
+        SourceHelpers.doc_comment_block_info(buffer, anchor_bol_range.begin_pos) ||
+          SourceHelpers.doc_comment_block_info(buffer, def_bol_range.begin_pos)
       end
 
-      # +Docscribe::InlineRewriter::Collector#const_name+ -> Object
-      #
       # Method documentation.
       #
       # @private
-      # @param [Object] node Param documentation.
+      # @param [Object] buffer Param documentation.
+      # @param [Object] insertion Param documentation.
       # @return [Object]
-      def const_name(node)
-        return 'Object' unless node
-
-        case node.type
-        when :const
-          scope, name = *node
-          scope_name = scope ? const_name(scope) : nil
-          [scope_name, name].compact.join('::')
-        when :cbase
-          '' # leading ::
-        else
-          node.loc.expression.source # fallback
-        end
+      def method_comment_block_removal_range(buffer, insertion)
+        anchor_bol_range, def_bol_range = method_bol_ranges(buffer, insertion)
+
+        SourceHelpers.comment_block_removal_range(buffer, anchor_bol_range.begin_pos) ||
+          SourceHelpers.comment_block_removal_range(buffer, def_bol_range.begin_pos)
       end
 
-      # +Docscribe::InlineRewriter::Collector#process_body+ -> Object
+      # Method documentation.
       #
+      # @private
+      # @param [Object] buffer Param documentation.
+      # @param [Object] insertion Param documentation.
+      # @return [Array]
+      def method_bol_ranges(buffer, insertion)
+        anchor_node = anchor_node_for(insertion)
+        [
+          SourceHelpers.line_start_range(buffer, anchor_node),
+          SourceHelpers.line_start_range(buffer, insertion.node)
+        ]
+      end
+
       # Method documentation.
       #
       # @private
-      # @param [Object] body Param documentation.
-      # @param [Object] ctx Param documentation.
+      # @param [Object] insertion Param documentation.
+      # @raise [StandardError]
       # @return [Object]
-      def process_body(body, ctx)
-        return unless body
+      # @return [Object] if StandardError
+      def method_line_for(insertion)
+        anchor_node_for(insertion).loc.expression.line
+      rescue StandardError
+        insertion.node.loc.expression.line
+      end
 
-        if body.type == :begin
-          body.children.each { |child| process_stmt(child, ctx) }
+      # Method documentation.
+      #
+      # @private
+      # @param [Object] insertion Param documentation.
+      # @return [Object]
+      def anchor_node_for(insertion)
+        if insertion.respond_to?(:anchor_node) && insertion.anchor_node
+          insertion.anchor_node
         else
-          process_stmt(body, ctx)
+          insertion.node
         end
       end
     end