docscribe 1.6.0 → 1.6.2

data/lib/docscribe/inline_rewriter/doc_builder.rb

@@ -3,6 +3,9 @@
 require 'docscribe/plugin'
 require 'docscribe/infer'
 require 'docscribe/inline_rewriter/source_helpers'
+require 'docscribe/types/yard/validator'
+require 'docscribe/validator/type_mismatch_validator'
+require 'docscribe/validator/generic_compatibility'
 
 module Docscribe
   module InlineRewriter
@@ -63,9 +66,9 @@ module Docscribe
       # Build
       #
       # @note module_function: defines #build (visibility: private)
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Object] opts additional keyword options forwarded to doc_setup
+      # @param [Hash<Symbol, Object>] opts additional keyword options forwarded to doc_setup
       # @raise [StandardError]
       # @return [String, nil]
       # @return [nil] if StandardError
@@ -82,10 +85,10 @@ module Docscribe
       # Build merge additions
       #
       # @note module_function: defines #build_merge_additions (visibility: private)
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [Array<String>] existing_lines existing doc comment lines being merged
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Object] options additional keyword options forwarded to downstream methods
+      # @param [Hash<Symbol, Object>] options additional keyword options forwarded to downstream methods
       # @raise [StandardError]
       # @return [String, nil]
       # @return [nil] if StandardError
@@ -105,12 +108,12 @@ module Docscribe
       # Build missing merge result
       #
       # @note module_function: defines #build_missing_merge_result (visibility: private)
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [Array<String>] existing_lines existing doc comment lines being merged
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Object] options additional keyword options forwarded to downstream methods
+      # @param [Hash<Symbol, Object>] options additional keyword options forwarded to downstream methods
       # @raise [StandardError]
-      # @return [Hash<Symbol, Object>]
+      # @return [Docscribe::InlineRewriter::DocBuilder::missingMergeResult]
       # @return [Hash] if StandardError
       def build_missing_merge_result(insertion, existing_lines:, config:, **options)
         setup = doc_setup(insertion, config: config, **options)
@@ -127,10 +130,10 @@ module Docscribe
       # Doc setup
       #
       # @note module_function: defines #doc_setup (visibility: private)
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Object] opts additional options
-      # @return [Hash<Symbol, Object>, nil]
+      # @param [Hash<Symbol, Object>] opts additional options
+      # @return [Docscribe::InlineRewriter::DocBuilder::setup, nil]
       def doc_setup(insertion, config:, **opts)
         node = insertion.node
         name = SourceHelpers.node_name(node)
@@ -143,10 +146,10 @@ module Docscribe
       # Build unsafe
       #
       # @note module_function: defines #build_unsafe (visibility: private)
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Hash<Symbol, Object>] setup method setup hash with name, normal_type, scope, visibility
-      # @param [Object] opts additional options including infer_default, fallback_type, treat_options_keyword_as_hash
+      # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, normal_type, scope, visibility
+      # @param [Hash<Symbol, Object>] opts additional options including infer_default, fallback_type, treat_options_keyword_as_hash
       # @return [String]
       def build_unsafe(insertion, config:, setup:, **opts)
         _, pl, rt = build_param_and_raise_info(setup, config, opts)
@@ -160,7 +163,7 @@ module Docscribe
       # Build param and raise info
       #
       # @note module_function: defines #build_param_and_raise_info (visibility: private)
-      # @param [Hash<Symbol, Object>] setup method setup hash with name, normal_type, scope, visibility
+      # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, normal_type, scope, visibility
       # @param [Docscribe::Config] config Docscribe configuration object
       # @param [Hash<Symbol, Object>] opts additional options including
       # @return [(Hash<String, String>, nil, Array<String>, nil, Array<String>)]
@@ -179,12 +182,12 @@ module Docscribe
       # Resolve doc setup
       #
       # @note module_function: defines #resolve_doc_setup! (visibility: private)
-      # @param [Hash<Symbol, Object>] setup method setup hash with name, normal_type, scope, visibility
+      # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, normal_type, scope, visibility
       # @param [Parser::AST::Node] node AST node whose source text to extract
       # @param [Symbol] name the method name string
       # @param [Docscribe::Config] config Docscribe configuration object
       # @param [Hash<Symbol, Object>] opts additional options including
-      # @return [Hash<Symbol, Object>]
+      # @return [Docscribe::InlineRewriter::DocBuilder::setup]
       def resolve_doc_setup!(setup, node, name, config, opts)
         external_sig = resolve_external_sig(setup[:container], setup[:scope], name, opts[:signature_provider], node)
         returns_spec = compute_returns_spec(node, config, opts[:param_types], opts[:core_rbs_provider],
@@ -202,9 +205,9 @@ module Docscribe
       # Extract base setup
       #
       # @note module_function: defines #extract_base_setup (visibility: private)
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [Symbol] name the method name string
-      # @return [Hash<Symbol, Object>]
+      # @return [Docscribe::InlineRewriter::DocBuilder::setup]
       def extract_base_setup(insertion, name)
         n = insertion.node
         { node: n, name: name, indent: SourceHelpers.line_indent(n), scope: insertion.scope,
@@ -247,10 +250,10 @@ module Docscribe
       # @param [Parser::AST::Node] node AST node whose source text to extract
       # @param [Docscribe::Config] config Docscribe configuration object
       # @param [Hash<String, String>, nil] param_types hash accumulating parameter name-to-type mappings
-      # @param [Object] core_rbs_provider RBS type provider
+      # @param [Docscribe::Types::RBS::Provider, nil] core_rbs_provider RBS type provider
       # @param [Docscribe::Types::ProviderChain?] signature_provider
       # @param [String?] container
-      # @return [Hash<Symbol, Object>]
+      # @return [Docscribe::InlineRewriter::DocBuilder::returnsSpec]
       def compute_returns_spec(node, config, param_types, core_rbs_provider, # rubocop:disable Metrics/ParameterLists
                                signature_provider: nil, container: nil)
         Docscribe::Infer.returns_spec_from_node(
@@ -264,7 +267,7 @@ module Docscribe
       #
       # @note module_function: defines #parse_existing_doc_tags (visibility: private)
       # @param [Array<String>] lines existing doc comment lines
-      # @return [Hash<Symbol, Object>] parsed tag info
+      # @return [Docscribe::InlineRewriter::DocBuilder::parseInfo] parsed tag info
       def parse_existing_doc_tags(lines)
         init = init_parse_info
         tags_started = false
@@ -343,7 +346,7 @@ module Docscribe
       #
       # @note module_function: defines #parse_existing_tag_line (visibility: private)
       # @param [String] line the doc comment line
-      # @param [Hash<Symbol, Object>] info mutable parse info accumulator
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info mutable parse info accumulator
       # @param [Boolean] tags_started whether @tags have been seen
       # @return [Boolean] updated tags_started
       def parse_existing_tag_line(line, info, tags_started)
@@ -363,7 +366,7 @@ module Docscribe
       #
       # @note module_function: defines #start_note_tag (visibility: private)
       # @param [String] line doc comment line
-      # @param [Hash<Symbol, Object>] info parse info hash
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
       # @return [void]
       def start_note_tag(line, info)
         return if line.match?(/^\s*#\s*@note\s+module_function:/)
@@ -377,7 +380,7 @@ module Docscribe
       #
       # @note module_function: defines #append_note_continuation (visibility: private)
       # @param [String] line doc comment line
-      # @param [Hash<Symbol, Object>] info parse info hash
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
       # @return [Object]
       def append_note_continuation(line, info)
         return unless info[:last_tag] == :note && info[:note_lines].any?
@@ -388,7 +391,7 @@ module Docscribe
       # Init parse info
       #
       # @note module_function: defines #init_parse_info (visibility: private)
-      # @return [Hash<Symbol, Object>]
+      # @return [Docscribe::InlineRewriter::DocBuilder::parseInfo]
       def init_parse_info
         {
           param_names: {}, param_types: {}, param_descriptions: {},
@@ -405,7 +408,7 @@ module Docscribe
       #
       # @note module_function: defines #merge_dest_lines (visibility: private)
       # @param [Array<String>] existing_lines existing doc comment lines to merge into
-      # @param [Object] ctx merge context hash (setup, insertion, config, info, param_types)
+      # @param [Hash<Symbol, Object>] ctx merge context hash (setup, insertion, config, info, param_types)
       # @return [String, nil]
       def merge_dest_lines(existing_lines, **ctx)
         merge_lines_with_context(existing_lines, **ctx)
@@ -415,7 +418,7 @@ module Docscribe
       #
       # @note module_function: defines #merge_lines_with_context (visibility: private)
       # @param [Array<String>] existing_lines existing doc comment lines being merged
-      # @param [Object] ctx merge context (setup, insertion, config, info, param_types)
+      # @param [Hash<Symbol, Object>] ctx merge context (setup, insertion, config, info, param_types)
       # @return [String]
       def merge_lines_with_context(existing_lines, **ctx)
         s = ctx[:setup]
@@ -445,7 +448,7 @@ module Docscribe
       #
       # @note module_function: defines #merge_all_tag_lines (visibility: private)
       # @param [Array<String>] base_ary initial line array
-      # @param [Object] ctx context hash with setup, config, info, insertion, param_types
+      # @param [Hash<Symbol, Object>] ctx context hash with setup, config, info, insertion, param_types
       # @return [Array<String>]
       def merge_all_tag_lines(base_ary, **ctx)
         line_ary = base_ary.dup
@@ -497,9 +500,9 @@ module Docscribe
       # @note module_function: defines #merge_return_line (visibility: private)
       # @param [Array<String>] line_ary output line array
       # @param [String] indent indentation string for doc comment lines
-      # @param [Hash<Symbol, Object>] setup method setup hash with node, name, types, scope
+      # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with node, name, types, scope
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with visibility flags
       # @return [void]
       def merge_return_line(line_ary, indent, setup, config, info)
         emit_ret = config.emit_return_tag?(setup[:scope], setup[:visibility])
@@ -512,12 +515,12 @@ module Docscribe
       # Collect all missing
       #
       # @note module_function: defines #collect_all_missing (visibility: private)
-      # @param [Hash<Symbol, Object>] setup resolved setup hash with node, name, indent, types
-      # @param [Hash<Symbol, Object>] info parsed existing doc tag information
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup resolved setup hash with node, name, indent, types
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parsed existing doc tag information
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [Docscribe::Config] config Docscribe configuration object
       # @param [Hash<Symbol, Object>] options additional options hash forwarded to missing collector
-      # @return [Hash<Symbol, Object>]
+      # @return [Docscribe::InlineRewriter::DocBuilder::missingMergeResult]
       def collect_all_missing(setup, info, insertion, config, options)
         s = setup
         ctx = { node: s[:node], indent: s[:indent], config: config, external_sig: s[:external_sig],
@@ -531,7 +534,7 @@ module Docscribe
       #
       # @note module_function: defines #collect_missing_all (visibility: private)
       # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
-      # @return [Hash<Symbol, Object>]
+      # @return [Docscribe::InlineRewriter::DocBuilder::missingMergeResult]
       def collect_missing_all(ctx)
         lines = [] #: Array[String]
         reasons = [] #: Array[Hash[Symbol, untyped]]
@@ -549,7 +552,7 @@ module Docscribe
       #
       # @note module_function: defines #extract_all_comment_tags (visibility: private)
       # @param [String] line single comment line
-      # @param [Hash<Symbol, Object>] info parse info hash
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
       # @return [void]
       def extract_all_comment_tags(line, info)
         extract_param_info(line, info[:param_names], info[:param_types], info[:param_descriptions])
@@ -585,7 +588,7 @@ module Docscribe
       #
       # @note module_function: defines #extract_return_info (visibility: private)
       # @param [String] line a single doc comment line to parse
-      # @param [Hash<Symbol, Object>] info parse info hash to update with return data
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with return data
       # @return [void]
       def extract_return_info(line, info)
         return unless line.match?(/^\s*#\s*@return\b/)
@@ -595,10 +598,26 @@ module Docscribe
         return unless (m = content.match(/@return\s+/))
 
         return_type, return_desc = parse_return_rest(m.post_match)
-        info[:return_type] = return_type if return_type
+        return unless return_type
+        # Rescue-conditional `@return [X] if Error` tags describe rescue
+        # branches (see rescue_conditional_returns) and must not overwrite
+        # the main return type — otherwise check demands the conditional
+        # type while update_types regenerates it, ping-ponging forever.
+        return if conditional_return_desc?(return_desc)
+
+        info[:return_type] = return_type
         info[:return_description] = return_desc if return_desc
       end
 
+      # Whether a return description marks a rescue-conditional tag.
+      #
+      # @note module_function: defines #conditional_return_desc? (visibility: private)
+      # @param [String, nil] desc description after the type brackets
+      # @return [Boolean] true for "if Error" suffixes
+      def conditional_return_desc?(desc)
+        desc.to_s.start_with?('if ')
+      end
+
       # Parse return type from rest string
       #
       # @note module_function: defines #parse_return_rest (visibility: private)
@@ -618,7 +637,7 @@ module Docscribe
       #
       # @note module_function: defines #track_last_tag (visibility: private)
       # @param [String] content
-      # @param [Hash<Symbol, Object>] info parse info hash
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
       # @return [void]
       def track_last_tag(content, info)
         tag = content.match(/@(\w+)/)&.[](1)&.to_sym
@@ -633,7 +652,7 @@ module Docscribe
       #
       # @note module_function: defines #append_tag_continuation (visibility: private)
       # @param [String] content tag continuation text
-      # @param [Hash<Symbol, Object>] info parse info hash
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
       # @return [void]
       def append_tag_continuation(content, info)
         text = content.strip
@@ -647,7 +666,7 @@ module Docscribe
       #
       # @note module_function: defines #append_to_return_description (visibility: private)
       # @param [String] text text to append
-      # @param [Hash<Symbol, Object>] info parse info hash
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
       # @return [void]
       def append_to_return_description(text, info)
         if info[:return_description]
@@ -661,7 +680,7 @@ module Docscribe
       #
       # @note module_function: defines #append_to_param_description (visibility: private)
       # @param [String] text text to append
-      # @param [Hash<Symbol, Object>] info parse info hash
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
       # @return [void]
       def append_to_param_description(text, info)
         pname = info[:last_param]
@@ -678,7 +697,7 @@ module Docscribe
       #
       # @note module_function: defines #extract_visibility_info (visibility: private)
       # @param [String] line a single doc comment line to parse
-      # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with visibility flags
       # @return [void]
       def extract_visibility_info(line, info)
         info[:has_private] ||= line.match?(/^\s*#\s*@private\b/)
@@ -718,17 +737,37 @@ module Docscribe
       def extract_raise_types_from_line(line)
         return [] unless line.match?(/^\s*#\s*@raise\b/)
 
-        if (m = line.match(/^\s*#\s*@raise\s*\[([^\]]+)\]/))
-          parse_raise_bracket_list(m[1]) # steep:ignore ArgumentTypeMismatch
-        elsif (m = line.match(/^\s*#\s*@raise\s+([A-Z]\w*(?:::[A-Z]\w*)*)/))
-          [m[1]]
-        else
-          []
-        end
+        bracketed_raise_types(line) || bare_raise_type(line) || []
       rescue StandardError
         []
       end
 
+      # Bracketed raise types from line
+      #
+      # @note module_function: defines #bracketed_raise_types (visibility: private)
+      # @param [String] line a `@raise` doc line
+      # @return [Array<String>, nil]
+      def bracketed_raise_types(line)
+        m = line.match(/^\s*#\s*@raise\s*\[([^\]]+)\]/)
+        return nil unless m
+
+        captured = m[1]
+        captured ? parse_raise_bracket_list(captured) : []
+      end
+
+      # Bare raise type from line
+      #
+      # @note module_function: defines #bare_raise_type (visibility: private)
+      # @param [String] line a `@raise` doc line
+      # @return [String, nil]
+      def bare_raise_type(line)
+        m = line.match(/^\s*#\s*@raise\s+([A-Z]\w*(?:::[A-Z]\w*)*)/)
+        return nil unless m
+
+        captured = m[1]
+        captured ? [captured] : []
+      end
+
       # Parse raise bracket list
       #
       # @note module_function: defines #parse_raise_bracket_list (visibility: private)
@@ -826,7 +865,7 @@ module Docscribe
       # @param [String] indent indentation string for the doc line
       # @param [Symbol] visibility method visibility symbol
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with visibility flags
       # @return [Array<String>]
       def merge_visibility_tag_lines(indent, visibility, config, info)
         return [] unless config.emit_visibility_tags?
@@ -844,9 +883,9 @@ module Docscribe
       #
       # @note module_function: defines #merge_module_function_note_lines (visibility: private)
       # @param [String] indent indentation string for the doc line
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [String] name the method name string
-      # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with visibility flags
       # @return [Array<String>]
       def merge_module_function_note_lines(indent, insertion, name, info)
         return [] unless insertion.respond_to?(:module_function) && insertion.module_function && !info[:has_module_function_note]
@@ -861,7 +900,7 @@ module Docscribe
       # @param [Parser::AST::Node] node AST node whose source text to extract
       # @param [String] indent indentation string for the doc line
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Object] opts additional options including external_sig, param_types, info
+      # @param [Hash<Symbol, Object>] opts additional options including external_sig, param_types, info
       # @return [Array<String>]
       def merge_param_lines(node, indent, config:, **opts)
         return [] unless config.emit_param_tags?
@@ -885,7 +924,7 @@ module Docscribe
       # @param [Parser::AST::Node] node AST node whose source text to extract
       # @param [String] indent indentation string for the doc line
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with visibility flags
       # @return [Array<String>]
       def merge_raise_tag_lines(node, indent, config, info)
         return [] unless config.emit_raise_tags?
@@ -902,7 +941,7 @@ module Docscribe
       # @param [String] indent indentation string for the doc line
       # @param [String] normal_type resolved return type
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Object] opts additional options including scope, visibility, info
+      # @param [Hash<Symbol, Object>] opts additional options including scope, visibility, info
       # @return [String, nil]
       def merge_return_tag_line(indent, normal_type, config:, **opts)
         return unless config.emit_return_tag?(opts[:scope], opts[:visibility])
@@ -917,7 +956,7 @@ module Docscribe
       # @param [String] indent indentation string for the doc line
       # @param [Array<(Array<String>, String)>] rescue_specs rescue type specs
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
+      # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with visibility flags
       # @return [Array<String>]
       def merge_rescue_return_lines(indent, rescue_specs, config, info)
         return [] unless config.emit_rescue_conditional_returns?
@@ -933,7 +972,7 @@ module Docscribe
       # @note module_function: defines #collect_missing_visibility! (visibility: private)
       # @param [Array<String>] lines array of output doc lines being accumulated
       # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
-      # @param [Object] ctx merged context hash with info and indent
+      # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
       # @return [void]
       def collect_missing_visibility!(lines, reasons, **ctx)
         return unless ctx[:config].emit_visibility_tags?
@@ -975,7 +1014,7 @@ module Docscribe
       # @note module_function: defines #collect_missing_module_function_note! (visibility: private)
       # @param [Array<String>] lines array of output doc lines being accumulated
       # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
-      # @param [Object] ctx merged context hash with info and indent
+      # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
       # @return [void]
       def collect_missing_module_function_note!(lines, reasons, **ctx)
         insertion = ctx[:insertion]
@@ -994,7 +1033,7 @@ module Docscribe
       # @note module_function: defines #collect_missing_params! (visibility: private)
       # @param [Array<String>] lines array of output doc lines being accumulated
       # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
-      # @param [Object] ctx merged context hash with info and indent
+      # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
       # @return [void]
       def collect_missing_params!(lines, reasons, **ctx)
         return unless ctx[:config].emit_param_tags?
@@ -1019,14 +1058,105 @@ module Docscribe
         pname = extract_param_name_from_param_line(param_line)
         return unless pname
 
-        if !ctx[:info][:param_names].include?(pname)
-          lines << "#{param_line}\n"
-          reasons << { type: :missing_param, message: "missing @param #{pname}", extra: { param: pname } }
-        elsif ctx[:external_sig] && ctx[:info][:param_types][pname]
+        if missing_param?(pname, ctx)
+          handle_missing_param(pname, param_line, lines, reasons)
+        elsif existing_param_type?(pname, ctx)
+          handle_existing_param(pname, param_line, lines, reasons, ctx)
+        end
+      end
+
+      # @note module_function: defines #missing_param? (visibility: private)
+      # @param [String] pname
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [Boolean]
+      def missing_param?(pname, ctx)
+        !ctx[:info][:param_names].include?(pname)
+      end
+
+      # @note module_function: defines #existing_param_type? (visibility: private)
+      # @param [String] pname
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [Boolean]
+      def existing_param_type?(pname, ctx)
+        !!ctx[:info][:param_types][pname]
+      end
+
+      # @note module_function: defines #handle_missing_param (visibility: private)
+      # @param [String] pname
+      # @param [String] param_line
+      # @param [Array<String>] lines
+      # @param [Array<Hash<Symbol, Object>>] reasons
+      # @return [void]
+      def handle_missing_param(pname, param_line, lines, reasons)
+        lines << "#{param_line}\n"
+        reasons << { type: :missing_param, message: "missing @param #{pname}", extra: { param: pname } }
+      end
+
+      # @note module_function: defines #handle_existing_param (visibility: private)
+      # @param [String] pname
+      # @param [String] param_line
+      # @param [Array<String>] lines
+      # @param [Array<Hash<Symbol, Object>>] reasons
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [void]
+      def handle_existing_param(pname, param_line, lines, reasons, ctx)
+        yard_type = ctx[:info][:param_types][pname]
+        if invalid_yard_type?(yard_type)
+          handle_invalid_param(pname, param_line, yard_type, lines, reasons)
+        elsif param_needs_update?(ctx)
           collect_updated_param(param_line, pname, lines, reasons, ctx)
         end
       end
 
+      # @note module_function: defines #handle_invalid_param (visibility: private)
+      # @param [String] pname
+      # @param [String] param_line
+      # @param [String] yard_type
+      # @param [Array<String>] lines
+      # @param [Array<Hash<Symbol, Object>>] reasons
+      # @return [void]
+      def handle_invalid_param(pname, param_line, yard_type, lines, reasons)
+        lines << "#{param_line}\n"
+        reasons << {
+          type: :invalid_type,
+          message: "invalid YARD type [#{yard_type}] for @param #{pname}",
+          source: 'syntax',
+          extra: { param: pname }
+        }
+      end
+
+      # @note module_function: defines #param_needs_update? (visibility: private)
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [Boolean]
+      def param_needs_update?(ctx)
+        should_validate_param?(ctx) || !!ctx[:external_sig]
+      end
+
+      # Whether a YARD type string has invalid syntax.
+      #
+      # Called from both param (above) and return (below) validation, so no
+      # waterfall placement satisfies the ordering cop — exempt.
+      #
+      # @note module_function: defines #invalid_yard_type? (visibility: private)
+      # @param [String?] type_str
+      # @return [Boolean]
+      def invalid_yard_type?(type_str) # rubocop:disable SortedMethodsByCall/Waterfall
+        return false if type_str.nil? || type_str.strip.empty?
+        return true if type_str.match?(/\d/)
+        return true if type_str.match?(/[^\x00-\x7F]/)
+
+        !Types::Yard::Validator.valid?(type_str)
+      end
+
+      # Whether param validation should run via inferred/external types.
+      #
+      # @note module_function: defines #should_validate_param? (visibility: private)
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [Boolean]
+      def should_validate_param?(ctx)
+        ctx[:config].respond_to?(:validate_types?) && ctx[:config].validate_types?
+      end
+
       # Collect updated param
       #
       # @note module_function: defines #collect_updated_param (visibility: private)
@@ -1038,12 +1168,48 @@ module Docscribe
       # @return [void]
       def collect_updated_param(param_line, pname, lines, reasons, ctx)
         new_type = extract_param_type_from_param_line(param_line)
-        return unless new_type && ctx[:info][:param_types][pname] != new_type
+        return unless param_type_changed?(pname, new_type, ctx)
+        return if fallback_skipped?(new_type, ctx)
+
+        append_param_update(param_line, pname, new_type, lines, reasons, ctx)
+      end
+
+      # @note module_function: defines #param_type_changed? (visibility: private)
+      # @param [String] pname
+      # @param [String, nil] new_type
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [Boolean]
+      def param_type_changed?(pname, new_type, ctx)
+        yard = ctx[:info][:param_types][pname]
+        return false unless new_type && yard
+        return false if normalize_type(yard) == normalize_type(new_type)
+        return false if generic_compatible?(yard, new_type)
+
+        yard != new_type
+      end
 
+      # @note module_function: defines #fallback_skipped? (visibility: private)
+      # @param [String, nil] new_type
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [Boolean]
+      def fallback_skipped?(new_type, ctx)
+        ctx[:config].respond_to?(:validate_types?) && ctx[:config].validate_types? && (new_type == ctx[:config].fallback_type)
+      end
+
+      # @note module_function: defines #append_param_update (visibility: private)
+      # @param [String] param_line
+      # @param [String] pname
+      # @param [String, nil] new_type
+      # @param [Array<String>] lines
+      # @param [Array<Hash<Symbol, Object>>] reasons
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [void]
+      def append_param_update(param_line, pname, new_type, lines, reasons, ctx) # rubocop:disable Metrics/ParameterLists
         lines << "#{param_line}\n" unless ctx[:strategy] == :safe
         reasons << {
           type: :updated_param,
           message: "updated @param #{pname} from #{ctx[:info][:param_types][pname]} to #{new_type}",
+          source: ctx[:external_sig] ? 'rbs' : 'infer',
           extra: { param: pname }
         }
       end
@@ -1071,7 +1237,7 @@ module Docscribe
       # @param [String] indent indentation string for the doc line
       # @param [Docscribe::Config] config Docscribe configuration object
       # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
-      # @param [Object] kwargs additional keyword args including insertion, params_lines, raise_types, override_tags
+      # @param [Hash<Symbol, Object>] kwargs additional keyword args including insertion, params_lines, raise_types, override_tags
       # @return [Array<String>, nil]
       def build_all_param_lines(args, indent, config, external_sig: nil, **kwargs)
         param_lines = [] #: Array[String]
@@ -1101,9 +1267,9 @@ module Docscribe
       # Build doc lines
       #
       # @note module_function: defines #build_doc_lines (visibility: private)
-      # @param [Hash<Symbol, Object>] setup method setup hash with indent, name, types, scope
+      # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with indent, name, types, scope
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Object] kwargs additional keyword args including insertion, params_lines, raise_types, override_tags
+      # @param [Hash<Symbol, Object>] kwargs additional keyword args including insertion, params_lines, raise_types, override_tags
       # @return [Array<String>]
       def build_doc_lines(setup, config:, **kwargs)
         i = setup[:indent]
@@ -1118,8 +1284,8 @@ module Docscribe
       #
       # @note module_function: defines #assemble_doc_lines (visibility: private)
       # @param [String] indent indent
-      # @param [Hash<Symbol, Object>] setup setup
-      # @param [Object] ctx context hash with config, insertion, params_lines, raise_types, override_tags
+      # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup setup
+      # @param [Hash<Symbol, Object>] ctx context hash with config, insertion, params_lines, raise_types, override_tags
       # @return [Array<String>]
       def assemble_doc_lines(indent, setup, **ctx)
         line_ary = build_header_lines(
@@ -1138,7 +1304,7 @@ module Docscribe
       # @note module_function: defines #append_assemble_body_lines (visibility: private)
       # @param [Array<String>] line_ary output line array
       # @param [String] indent indentation string for doc comment lines
-      # @param [Hash<Symbol, Object>] setup method setup hash with name, types, scope
+      # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, types, scope
       # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
       # @return [void]
       def append_assemble_body_lines(line_ary, indent, setup, ctx)
@@ -1149,7 +1315,7 @@ module Docscribe
       #
       # @note module_function: defines #build_all_body_tags (visibility: private)
       # @param [String] indent indentation string for doc comment lines
-      # @param [Hash<Symbol, Object>] setup method setup hash with name, types, scope
+      # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, types, scope
       # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
       # @return [Array<String>]
       def build_all_body_tags(indent, setup, ctx)
@@ -1162,9 +1328,9 @@ module Docscribe
       #
       # @note module_function: defines #core_body_tags (visibility: private)
       # @param [String] indent indentation string for doc comment lines
-      # @param [Hash<Symbol, Object>] setup method setup hash with name, types, scope
+      # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, types, scope
       # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
-      # @return [Array<Object>]
+      # @return [Array<String>]
       def core_body_tags(indent, setup, ctx)
         config, insertion = ctx.values_at(:config, :insertion)
         [
@@ -1198,7 +1364,7 @@ module Docscribe
       #
       # @note module_function: defines #build_return_line_if_needed (visibility: private)
       # @param [String] indent indentation string for doc comment lines
-      # @param [Hash<Symbol, Object>] setup method setup hash with name, normal_type, scope, visibility
+      # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, normal_type, scope, visibility
       # @param [Docscribe::Config] config Docscribe configuration object
       # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
       # @return [Array<String>]
@@ -1232,7 +1398,7 @@ module Docscribe
       # @param [String] indent indentation string for doc comment lines
       # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
       # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
-      # @param [Object] opts additional options for param formatting (fallback_type, param_tag_style, etc.)
+      # @param [Hash<Symbol, Object>] opts additional options for param formatting (fallback_type, param_tag_style, etc.)
       # @return [Array<String>]
       def build_param_line(arg_node, indent, external_sig, param_types_override, **opts)
         method_name = :"build_#{arg_node.type}_line"
@@ -1253,7 +1419,7 @@ module Docscribe
       # @note module_function: defines #build_header_lines (visibility: private)
       # @param [String] indent indentation string for the doc line
       # @param [Docscribe::Config] config Docscribe configuration object
-      # @param [Object] opts additional options including container, method_symbol, name, normal_type
+      # @param [Hash<Symbol, Object>] opts additional options including container, method_symbol, name, normal_type
       # @return [Array<String>]
       def build_header_lines(indent, config:, **opts)
         if config.emit_header?
@@ -1309,7 +1475,7 @@ module Docscribe
       #
       # @note module_function: defines #build_module_function_note_lines (visibility: private)
       # @param [String] indent indentation string for the doc line
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [String] name the method name string
       # @return [Array<String>]
       def build_module_function_note_lines(indent, insertion, name)
@@ -1371,10 +1537,10 @@ module Docscribe
       # Build plugin tag lines
       #
       # @note module_function: defines #build_plugin_tag_lines (visibility: private)
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [String] indent indentation string for the doc line
       # @param [String] normal_type resolved return type
-      # @param [Array<Object>, nil] override_tags plugin tag overrides
+      # @param [Array<Docscribe::Plugin::Tag>, nil] override_tags plugin tag overrides
       # @return [Array<String>]
       def build_plugin_tag_lines(insertion, indent, normal_type, override_tags)
         plugin_tags = Docscribe::Plugin.run_tag_plugins(build_plugin_context(insertion, normal_type: normal_type))
@@ -1389,7 +1555,7 @@ module Docscribe
       # @param [String] indent indentation string for doc comment lines
       # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
       # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
-      # @param [Object] opts additional options for param formatting
+      # @param [Hash<Symbol, Object>] opts additional options for param formatting
       # @return [String]
       def build_arg_line(arg_node, indent, external_sig, param_types_override, **opts)
         pname = arg_node.children.first.to_s
@@ -1407,7 +1573,7 @@ module Docscribe
       # @param [String] indent indentation string for doc comment lines
       # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
       # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
-      # @param [Object] opts additional options for param formatting
+      # @param [Hash<Symbol, Object>] opts additional options for param formatting
       # @return [Array<String>]
       def build_optarg_lines(arg_node, indent, external_sig, param_types_override, **opts)
         pname, default = *arg_node
@@ -1463,7 +1629,7 @@ module Docscribe
       # @param [String] indent indentation string for doc comment lines
       # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
       # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
-      # @param [Object] opts additional options for param formatting
+      # @param [Hash<Symbol, Object>] opts additional options for param formatting
       # @return [String]
       def build_kwarg_line(arg_node, indent, external_sig, param_types_override, **opts)
         pname = arg_node.children.first.to_s
@@ -1481,7 +1647,7 @@ module Docscribe
       # @param [String] indent indentation string for doc comment lines
       # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
       # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
-      # @param [Object] opts additional options for param formatting
+      # @param [Hash<Symbol, Object>] opts additional options for param formatting
       # @return [String]
       def build_kwoptarg_line(arg_node, indent, external_sig, param_types_override, **opts)
         pname, default = *arg_node
@@ -1502,7 +1668,7 @@ module Docscribe
       # @param [String] indent indentation string for doc comment lines
       # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
       # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
-      # @param [Object] opts additional options for param formatting
+      # @param [Hash<Symbol, Object>] opts additional options for param formatting
       # @return [String]
       def build_restarg_line(arg_node, indent, external_sig, param_types_override, **opts)
         pname = (arg_node.children.first || 'args').to_s
@@ -1523,7 +1689,7 @@ module Docscribe
       # @param [String] indent indentation string for doc comment lines
       # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
       # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
-      # @param [Object] opts additional options for param formatting
+      # @param [Hash<Symbol, Object>] opts additional options for param formatting
       # @return [String]
       def build_kwrestarg_line(arg_node, indent, external_sig, param_types_override, **opts)
         pname = (arg_node.children.first || 'kwargs').to_s
@@ -1540,7 +1706,7 @@ module Docscribe
       # @param [String] indent indentation string for doc comment lines
       # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
       # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
-      # @param [Object] opts additional options for param formatting
+      # @param [Hash<Symbol, Object>] opts additional options for param formatting
       # @return [String]
       def build_blockarg_line(arg_node, indent, external_sig, param_types_override, **opts)
         pname = (arg_node.children.first || 'block').to_s
@@ -1558,7 +1724,7 @@ module Docscribe
       # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
       # @param [String] pname the parameter name string
       # @param [String] infer_name parameter name string or transformed version for inference
-      # @param [Object] opts additional options including infer_default, fallback_type, treat_options_keyword_as_hash
+      # @param [Hash<Symbol, Object>] opts additional options including infer_default, fallback_type, treat_options_keyword_as_hash
       # @return [String]
       def lookup_param_type(external_sig, param_types_override, pname, infer_name, **opts)
         external_sig&.param_types&.[](pname) ||
@@ -1705,7 +1871,7 @@ module Docscribe
       #
       # @note module_function: defines #override_param_type_for (visibility: private)
       # @param [String] pname the parameter name to look up
-      # @param [Hash<Object, Object>, nil] override_map hash map of parameter name to override type
+      # @param [Hash<Object, String>, nil] override_map hash map of parameter name to override type
       # @return [String, nil]
       def override_param_type_for(pname, override_map)
         return nil unless override_map
@@ -1823,7 +1989,7 @@ module Docscribe
       # @note module_function: defines #collect_missing_raises! (visibility: private)
       # @param [Array<String>] lines array of output doc lines being accumulated
       # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
-      # @param [Object] ctx merged context hash with info and indent
+      # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
       # @return [void]
       def collect_missing_raises!(lines, reasons, **ctx)
         return unless ctx[:config].emit_raise_tags?
@@ -1843,18 +2009,234 @@ module Docscribe
       # @note module_function: defines #collect_missing_return! (visibility: private)
       # @param [Array<String>] lines array of output doc lines being accumulated
       # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
-      # @param [Object] ctx merged context hash with info and indent
+      # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
       # @return [void]
       def collect_missing_return!(lines, reasons, **ctx)
         return unless ctx[:config].emit_return_tag?(ctx[:scope], ctx[:visibility])
 
         if !ctx[:info][:has_return]
           record_missing_return(lines, reasons, ctx)
+        elsif invalid_yard_return?(ctx)
+          record_invalid_return(lines, reasons, ctx)
         elsif return_type_changed?(ctx)
           record_updated_return(lines, reasons, ctx)
+        elsif should_validate_return?(ctx) && mismatched_return?(ctx) # rubocop:disable Lint/DuplicateBranch
+          record_updated_return(lines, reasons, ctx)
         end
       end
 
+      # Whether YARD return type has invalid syntax.
+      #
+      # @note module_function: defines #invalid_yard_return? (visibility: private)
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [Boolean]
+      def invalid_yard_return?(ctx)
+        yard = ctx[:info][:return_type]
+        return false unless yard
+
+        invalid_yard_type?(yard)
+      end
+
+      # Record invalid return type.
+      #
+      # @note module_function: defines #record_invalid_return (visibility: private)
+      # @param [Array<String>] lines
+      # @param [Array<Hash<Symbol, Object>>] reasons
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [void]
+      def record_invalid_return(lines, reasons, ctx)
+        yard = ctx[:info][:return_type]
+        lines << "#{ctx[:indent]}# @return [#{ctx[:normal_type]}]\n"
+        reasons << {
+          type: :invalid_type,
+          message: "invalid YARD type [#{yard}] for @return, expected [#{ctx[:normal_type]}]",
+          source: 'syntax'
+        }
+      end
+
+      # Whether return validation should run via inferred types.
+      #
+      # @note module_function: defines #should_validate_return? (visibility: private)
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [Boolean]
+      def should_validate_return?(ctx)
+        ctx[:config].respond_to?(:validate_types?) && ctx[:config].validate_types?
+      end
+
+      # Whether YARD return mismatches expected inferred/external type.
+      #
+      # Silences when expected is fallback (uncertain).
+      #
+      # @note module_function: defines #mismatched_return? (visibility: private)
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [Boolean]
+      def mismatched_return?(ctx)
+        yard, expected, fallback = mismatched_return_types(ctx)
+        return false unless yard && expected
+        return false if expected_suppressed?(expected, fallback)
+
+        method_name = extract_method_name(ctx)
+        return false if yard_compatible?(yard, expected, fallback, method_name: method_name)
+        return false if types_normalized_equal?(yard, expected)
+
+        true
+      end
+
+      # Extract method name for void compatibility dynamic check.
+      #
+      # @note module_function: defines #extract_method_name (visibility: private)
+      # @param [Hash<Symbol, Object>] ctx context hash with insertion or node
+      # @raise [StandardError]
+      # @return [Symbol, nil]
+      # @return [nil] if StandardError
+      def extract_method_name(ctx)
+        insertion = ctx[:insertion]
+        node = insertion&.node || ctx[:node]
+        return nil unless node
+
+        SourceHelpers.node_name(node)
+      rescue StandardError
+        nil
+      end
+
+      # Extract yard/expected/fallback triple for return mismatch check.
+      #
+      # @note module_function: defines #mismatched_return_types (visibility: private)
+      # @param [Hash<Symbol, Object>] ctx
+      # @return [(String?, String?, String)]
+      def mismatched_return_types(ctx)
+        [ctx[:info][:return_type], ctx[:normal_type], ctx[:config].fallback_type]
+      end
+
+      # Whether expected type is suppressed as fallback.
+      #
+      # @note module_function: defines #expected_suppressed? (visibility: private)
+      # @param [String?] expected
+      # @param [String] fallback
+      # @return [Boolean]
+      def expected_suppressed?(expected, fallback)
+        expected == fallback || fallback_union?(expected, fallback)
+      end
+
+      # Whether yard type is compatible with expected via void/union/generic.
+      #
+      # @note module_function: defines #yard_compatible? (visibility: private)
+      # @param [String?] yard
+      # @param [String?] expected
+      # @param [String] fallback
+      # @param [String, Symbol, nil] method_name method name for void compatibility
+      # @return [Boolean]
+      def yard_compatible?(yard, expected, fallback, method_name: nil)
+        void_compatible?(yard, expected, fallback, method_name: method_name) ||
+          yard_in_expected_union?(yard, expected) ||
+          generic_compatible?(yard, expected, method_name: method_name)
+      end
+
+      # Whether types are equal after normalization (including optional "?").
+      #
+      # @note module_function: defines #types_normalized_equal? (visibility: private)
+      # @param [String?] yard
+      # @param [String?] expected
+      # @return [Boolean]
+      def types_normalized_equal?(yard, expected)
+        normalized_equal?(yard, expected) || optional_normalized_equal?(yard, expected)
+      end
+
+      # Whether normalized types are equal.
+      #
+      # @note module_function: defines #normalized_equal? (visibility: private)
+      # @param [String?] yard
+      # @param [String?] expected
+      # @return [Boolean]
+      def normalized_equal?(yard, expected)
+        normalize_type(yard) == normalize_type(expected)
+      end
+
+      # Whether optional-normalized types are equal.
+      #
+      # @note module_function: defines #optional_normalized_equal? (visibility: private)
+      # @param [String?] yard
+      # @param [String?] expected
+      # @return [Boolean]
+      def optional_normalized_equal?(yard, expected)
+        normalize_type(yard).delete_suffix('?') == normalize_type(expected).delete_suffix('?')
+      end
+
+      # Delegates to GenericCompatibility service (dynamic, map-dispatched, no hardcodes).
+      #
+      # @note module_function: defines #generic_compatible? (visibility: private)
+      # @param [String] yard
+      # @param [String] expected
+      # @param [String, Symbol, nil] method_name method name for void compatibility threading
+      # @return [Boolean]
+      def generic_compatible?(yard, expected, method_name: nil)
+        Docscribe::Validator::GenericCompatibility.compatible?(yard, expected, fallback_type: 'Object', method_name: method_name)
+      end
+
+      # Whether yard type is included in expected union (e.g. Boolean in Object, Boolean).
+      #
+      # @note module_function: defines #yard_in_expected_union? (visibility: private)
+      # @param [String] yard
+      # @param [String] expected
+      # @return [Boolean]
+      def yard_in_expected_union?(yard, expected)
+        normalized_yard = normalize_type(yard)
+        expected.split(',').any? { |part| normalize_type(part) == normalized_yard }
+      end
+
+      # Whether void YARD type is compatible with fallback union or initialize/setup dynamic.
+      #
+      # @note module_function: defines #void_compatible? (visibility: private)
+      # @param [String, nil] yard
+      # @param [String, nil] expected
+      # @param [String] fallback
+      # @param [String, Symbol, nil] method_name method name for dynamic check
+      # @return [Boolean]
+      def void_compatible?(yard, expected, fallback, method_name: nil) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength, Metrics/AbcSize
+        return false unless normalize_type(yard) == 'void'
+
+        return true if fallback_union?(expected, fallback) ||
+                       %w[nil void].include?(normalize_type(expected))
+
+        if method_name.to_s =~ /initialize|setup/
+          norm = normalize_type(expected).delete_suffix('?').strip
+          return true if norm == 'Hash' || norm.start_with?('Hash<') || norm.start_with?('Hash[')
+          return true if %w[self Boolean].include?(norm)
+        end
+
+        if method_name.to_s.end_with?('?')
+          norm = normalize_type(expected).delete_suffix('?').strip
+          return true if norm == 'Boolean'
+        end
+
+        false
+      end
+
+      # Whether a type string is a union of only fallback types (with optional `?`).
+      #
+      # @note module_function: defines #fallback_union? (visibility: private)
+      # @param [String, nil] type_str
+      # @param [String] fallback
+      # @return [Boolean]
+      def fallback_union?(type_str, fallback)
+        return false if type_str.nil? || type_str.strip.empty?
+
+        fallback_norm = normalize_type(fallback)
+        parts = type_str.to_s.split(',').map { |p| normalize_type(p.strip.delete_suffix('?').strip) }
+        parts.all? { |p| p == fallback_norm || p.empty? }
+      end
+
+      # Normalize type string for comparison (unify RBS/YARD syntax).
+      #
+      # @note module_function: defines #normalize_type (visibility: private)
+      # @param [String, nil] type_str
+      # @return [String]
+      def normalize_type(type_str)
+        s = type_str.to_s
+        s = s.sub(/#.*\z/m, '').strip unless s.lstrip.start_with?('#')
+        s.strip.squeeze(' ').gsub('[', '<').gsub(']', '>').gsub(/\buntyped\b/, 'Object').gsub(/\bFALLBACK_TYPE\b/, 'Object')
+      end
+
       # Record missing return
       #
       # @note module_function: defines #record_missing_return (visibility: private)
@@ -1877,7 +2259,8 @@ module Docscribe
       def record_updated_return(lines, reasons, ctx)
         lines << "#{ctx[:indent]}# @return [#{ctx[:normal_type]}]\n" unless ctx[:strategy] == :safe
         reasons << { type: :updated_return,
-                     message: "updated @return from #{ctx[:info][:return_type]} to #{ctx[:normal_type]}" }
+                     message: "updated @return from #{ctx[:info][:return_type]} to #{ctx[:normal_type]}",
+                     source: ctx[:external_sig] ? 'rbs' : 'infer' }
       end
 
       # Return type changed
@@ -1894,7 +2277,7 @@ module Docscribe
       # @note module_function: defines #collect_missing_rescue_returns! (visibility: private)
       # @param [Array<String>] lines array of output doc lines being accumulated
       # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
-      # @param [Object] ctx merged context hash with info and indent
+      # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
       # @return [void]
       def collect_missing_rescue_returns!(lines, reasons, **ctx)
         return unless ctx[:config].emit_rescue_conditional_returns?
@@ -1914,7 +2297,7 @@ module Docscribe
       # @note module_function: defines #collect_missing_plugin_tags! (visibility: private)
       # @param [Array<String>] lines array of output doc lines being accumulated
       # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
-      # @param [Object] ctx merged context hash with info and indent
+      # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
       # @return [void]
       def collect_missing_plugin_tags!(lines, reasons, **ctx)
         plugin_tags = Docscribe::Plugin.run_tag_plugins(build_plugin_context(ctx[:insertion],
@@ -1927,7 +2310,7 @@ module Docscribe
       # Record plugin tag
       #
       # @note module_function: defines #record_plugin_tag (visibility: private)
-      # @param [Object] tag plugin tag object to render and record
+      # @param [Docscribe::Plugin::Tag] tag plugin tag object to render and record
       # @param [Array<String>] lines array of output doc lines being accumulated
       # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
       # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
@@ -1944,7 +2327,7 @@ module Docscribe
       #
       # @note module_function: defines #debug_warn (visibility: private)
       # @param [StandardError] error the error that occurred
-      # @param [Object] insertion the method insertion being processed
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the method insertion being processed
       # @param [String] name the method name
       # @param [String] phase the processing phase
       # @return [void]
@@ -1958,7 +2341,7 @@ module Docscribe
       # Build debug location
       #
       # @note module_function: defines #build_debug_location (visibility: private)
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [String] name the method name string
       # @return [String]
       def build_debug_location(insertion, name)
@@ -1982,9 +2365,9 @@ module Docscribe
       # Build plugin context
       #
       # @note module_function: defines #build_plugin_context (visibility: private)
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [String] normal_type resolved return type
-      # @return [Object]
+      # @return [Docscribe::Plugin::Context]
       def build_plugin_context(insertion, normal_type:)
         node = insertion.node
         source = safe_node_source(node)
@@ -1994,11 +2377,11 @@ module Docscribe
       # New plugin context
       #
       # @note module_function: defines #new_plugin_context (visibility: private)
-      # @param [Object] insertion the collected method insertion object
+      # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
       # @param [Parser::AST::Node] node AST node whose source text to extract
       # @param [String] source method source text
       # @param [String] normal_type resolved return type
-      # @return [Object]
+      # @return [Docscribe::Plugin::Context]
       def new_plugin_context(insertion, node, source, normal_type)
         Docscribe::Plugin::Context.new(
           node: node,
@@ -2028,7 +2411,7 @@ module Docscribe
       # Render plugin tags
       #
       # @note module_function: defines #render_plugin_tags (visibility: private)
-      # @param [Array<Object>] tags plugin tag objects
+      # @param [Array<Docscribe::Plugin::Tag>] tags plugin tag objects
       # @param [String] indent indentation string for the doc line
       # @return [Array<String>]
       def render_plugin_tags(tags, indent)