docscribe 1.3.0 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ccc7ee30955f8dcc7c8d0335788e82878acfdf9136dcf7d956717e972804ffa
-  data.tar.gz: 24a76c793eb52f4fc5b21ad061e1f659744907ccb0c2b12cd886bd2f9b33c67c
+  metadata.gz: 765dd81d49b3cbf47c90f83f9e533a367da6590f84b15ca7e49de66c6140b5e1
+  data.tar.gz: b7c0607de2fb6e2344be24d4da58c1e03ab33755175783e1e6de8c934a8f2cdc
 SHA512:
-  metadata.gz: d1173ff834e00563b0d35cb9df4a05dc6a47db9f7f02d9ea8b7191d5eef3a984066c48c754efbe72c533dc830d983e65f64f001a167d897519e9e6d9a7993bf6
-  data.tar.gz: 4ed3ff6dbd216a5d0d2606170660a78b2492579624ad045757ef42123d92761cb97feda21f62f5b578e8dd2211b1f78a6d6ef73edd8ed50511eb807755857457
+  metadata.gz: f30b33860317c5b9914e6b6c633df75c35f11883d7524c3b832365431a5f47760eaaeb4daab3b20f358bad8cb088015b173d6848bf65b3d7cbba18a69fda5154
+  data.tar.gz: 66ac534ba8452880ee778ae1bf72ce571e9ea4bba481e5595172314df1f809eb62db87ec8b77cd4efb8c8cd37c85dd0c937b7fa8c263938ab46734ae03f5acda

data/lib/docscribe/cli/config_builder.rb

@@ -44,7 +44,7 @@ module Docscribe
         raw['filter']['files']['include'] = Array(raw['filter']['files']['include']) + options[:include_file]
         raw['filter']['files']['exclude'] = Array(raw['filter']['files']['exclude']) + options[:exclude_file]
 
-        if options[:rbs] || options[:sig_dirs].any?
+        if options[:rbs] || options[:rbs_collection] || options[:sig_dirs].any?
           raw['rbs'] ||= {}
           raw['rbs']['enabled'] = true
           raw['rbs']['sig_dirs'] = Array(raw['rbs']['sig_dirs']) + options[:sig_dirs] if options[:sig_dirs].any?

data/lib/docscribe/cli/run.rb

@@ -148,7 +148,9 @@ module Docscribe
             fail_paths: [],
             fail_changes: {},
             error_paths: [],
-            error_messages: {}
+            error_messages: {},
+            type_mismatch_paths: [],
+            type_mismatch_changes: {}
           }
         end
 
@@ -278,9 +280,18 @@ module Docscribe
         # @param [Hash] state shared processing state
         # @return [void]
         def handle_check_result(path, src:, out:, file_changes:, display_path:, options:, state:)
-          if out == src
-            options[:verbose] ? puts("OK #{display_path}") : print('.')
-            state[:checked_ok] += 1
+          type_mismatches = file_changes.select { |c| %i[updated_param updated_return].include?(c[:type]) }
+          has_real_changes = file_changes.any? { |c| !%i[updated_param updated_return].include?(c[:type]) }
+
+          if out == src && !has_real_changes
+            if type_mismatches.any?
+              state[:type_mismatch_paths] << path
+              state[:type_mismatch_changes][path] = type_mismatches
+              options[:verbose] ? puts("MT #{display_path}") : print('M')
+            else
+              state[:checked_ok] += 1
+              options[:verbose] ? puts("OK #{display_path}") : print('.')
+            end
             return
           end
 
@@ -350,13 +361,22 @@ module Docscribe
           puts
 
           checked_error = state[:error_paths].size
+          type_mismatch_count = state[:type_mismatch_paths].size
 
-          if state[:checked_fail].zero? && checked_error.zero?
+          if state[:checked_fail].zero? && checked_error.zero? && type_mismatch_count.zero?
             puts "Docscribe: OK (#{state[:checked_ok]} files checked)"
             return
           end
 
-          puts "Docscribe: FAILED (#{state[:checked_fail]} files need updates, #{checked_error} errors, #{state[:checked_ok]} ok)"
+          if state[:checked_fail].zero? && checked_error.zero?
+            puts "Docscribe: OK (#{state[:checked_ok]} files checked, #{type_mismatch_count} with type mismatches)"
+          else
+            parts = ["#{state[:checked_fail]} need updates"]
+            parts << "#{type_mismatch_count} type mismatches" if type_mismatch_count.positive?
+            parts << "#{checked_error} errors"
+            parts << "#{state[:checked_ok]} ok"
+            puts "Docscribe: FAILED (#{parts.join(', ')})"
+          end
 
           state[:fail_paths].each do |p|
             warn "Would update docs: #{p}"
@@ -367,6 +387,15 @@ module Docscribe
             end
           end
 
+          if options[:verbose] || options[:explain]
+            state[:type_mismatch_paths].each do |p|
+              warn "Type mismatches: #{p}"
+              Array(state[:type_mismatch_changes][p]).each do |change|
+                warn "  - #{format_change_reason(change)}"
+              end
+            end
+          end
+
           state[:error_paths].each do |p|
             warn "Error processing: #{p}"
             warn "  #{state[:error_messages][p]}" if state[:error_messages][p]

data/lib/docscribe/config/defaults.rb

@@ -14,7 +14,9 @@ module Docscribe
     # - optional Sorbet integration
     DEFAULT = {
       'emit' => {
-        'header' => true,
+        'header' => false,
+        'include_default_message' => true,
+        'include_param_documentation' => true,
         'param_tags' => true,
         'return_tag' => true,
         'visibility_tags' => true,
@@ -53,11 +55,12 @@ module Docscribe
         'exclude' => [],
         'files' => {
           'include' => [],
-          'exclude' => []
+          'exclude' => ['spec']
         }
       },
       'rbs' => {
         'enabled' => false,
+        'collection' => false,
         'sig_dirs' => ['sig'],
         'collapse_generics' => false
       },

data/lib/docscribe/config/rbs.rb

@@ -11,6 +11,7 @@ module Docscribe
     # @return [Docscribe::Types::RBS::Provider, nil]
     def rbs_provider
       return nil unless rbs_enabled?
+      return nil unless ruby_supports_rbs?
 
       @rbs_provider ||= begin
         require 'docscribe/types/rbs/provider'
@@ -30,8 +31,43 @@ module Docscribe
       fetch_bool(%w[rbs enabled], false)
     end
 
+    # Method documentation.
+    #
+    # @raise [LoadError]
+    # @return [Object]
+    def core_rbs_provider
+      return nil unless ruby_supports_rbs?
+
+      @core_rbs_provider ||= begin
+        require 'docscribe/types/rbs/provider'
+        Docscribe::Types::RBS::Provider.new(
+          sig_dirs: [],
+          collapse_generics: false
+        )
+      rescue LoadError
+        nil
+      end
+    end
+
+    private
+
+    # Method documentation.
+    #
+    # @private
+    # @return [Boolean]
+    def ruby_supports_rbs?
+      return true if RUBY_VERSION >= '3.0'
+
+      @rbs_warning_emitted ||= begin
+        warn 'Docscribe: RBS requires Ruby 3.0+. Falling back to inference.'
+        true
+      end
+      false
+    end
+
     # Signature directories used by the RBS provider.
     #
+    # @private
     # @return [Array<String>]
     def rbs_sig_dirs
       Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map(&:to_s)
@@ -43,7 +79,8 @@ module Docscribe
     # - `Hash<Symbol, String>` => `Hash`
     # - `Array<Integer>`       => `Array`
     #
-    # @return [Boolean]
+    # @private
+    # @return [Object]
     def rbs_collapse_generics?
       fetch_bool(%w[rbs collapse_generics], false)
     end

data/lib/docscribe/config/template.rb

@@ -14,187 +14,94 @@ module Docscribe
         ---
         # Docscribe configuration file
         #
-        # Inspect what safe doc updates would be applied:
-        #   bundle exec docscribe lib
-        #
-        # Apply safe doc updates:
-        #   bundle exec docscribe -a lib
-        #
-        # Apply aggressive doc updates (rebuild existing doc blocks):
-        #   bundle exec docscribe -A lib
+        # Docscribe works without this file — create it only for customization.
         #
+        # Quick start:
+        #   bundle exec docscribe lib          # check what would change
+        #   bundle exec docscribe -a lib       # apply safe updates
+        #   bundle exec docscribe -A lib       # rebuild all doc blocks
 
         emit:
-          # Emit the header line:
-          #
-          #   +MyClass#my_method+ -> ReturnType
-          header: false
-
-          # Whether to include the default placeholder line:
-          #   # Method documentation.
-          include_default_message: true
-
-          # Whether to append placeholder text to generated @param tags:
-          #   # @param [String] name Param documentation.
-          include_param_documentation: true
-
-          # Emit @param tags.
-          param_tags: true
-
-          # Emit @return tag (can be overridden per scope/visibility under methods:).
-          return_tag: true
-
-          # Emit @private / @protected tags based on Ruby visibility context.
-          visibility_tags: true
-
-          # Emit @raise tags inferred from rescue clauses / raise/fail calls.
-          raise_tags: true
-
-          # Emit conditional rescue return tags:
-          #
-          #   @return [String] if FooError, BarError
-          rescue_conditional_returns: true
-
-          # Generate @!attribute docs for attr_reader/attr_writer/attr_accessor.
-          attributes: false
+          # What to include in generated documentation
+          header: false                       # +MyClass#foo+ -> ReturnType
+          param_tags: true                    # @param tags
+          return_tag: true                    # @return tag
+          visibility_tags: true               # @private / @protected
+          raise_tags: true                    # @raise tags
+          rescue_conditional_returns: true    # @return [Type] if Error
+          attributes: false                   # @!attribute for attr_*
+
+          # Placeholder text for generated docs
+          include_default_message: true       # "Method documentation."
+          include_param_documentation: true   # "Param documentation."
 
         doc:
-          # Default text inserted into each generated doc block.
+          # Default text and formatting
           default_message: "Method documentation."
-
-          # Default text appended to generated @param tags.
           param_documentation: "Param documentation."
+          param_tag_style: "type_name"        # "type_name" or "name_type"
+          sort_tags: true
+          tag_order: ["todo", "note", "api", "private", "protected", "param", "option", "yieldparam", "raise", "return"]
 
-          # Style for generated @param tags:
-          # - type_name => @param [Type] name
-          # - name_type => @param name [Type]
-          param_tag_style: "type_name"
+        inference:
+          # Type inference behavior
+          fallback_type: "Object"             # when uncertain
+          nil_as_optional: true               # String | nil => String?
+          treat_options_keyword_as_hash: true # options: keyword => Hash
 
-          # Sort generated / merged tags in safe mode when possible.
-          sort_tags: true
+        filter:
+          # Which methods and files to process
+          # Method format: "Container#method" (instance) or "Container.method" (class)
+          # Supports globs ("*#initialize") and regex ("/^MyApp::.*$/")
+          include: []
+          exclude: []
+          visibilities: ["public", "protected", "private"]
+          scopes: ["instance", "class"]
 
-          # Tag order used when sorting contiguous tag runs.
-          tag_order: ["todo", "note", "api", "private", "protected", "param", "option", "yieldparam", "raise", "return"]
+          files:
+            # File paths relative to project root (globs or /regex/)
+            include: []
+            exclude: ["spec"]
 
         methods:
-          # Per-scope / per-visibility overrides.
+          # Override defaults per scope and visibility.
+          # Empty {} means "use values from `doc` section".
           #
           # Example:
-          # methods:
           #   instance:
           #     public:
           #       default_message: "Public API."
-          #       return_tag: true
+          #     private:
+          #       return_tag: false
           instance:
             public: {}
             protected: {}
             private: {}
-
           class:
             public: {}
             protected: {}
             private: {}
 
-        inference:
-          # Type used when inference is uncertain.
-          fallback_type: "Object"
-
-          # Whether nil unions become optional types (for example String | nil => String?).
-          nil_as_optional: true
-
-          # Special-case: treat keyword arg named options/options: as a Hash.
-          treat_options_keyword_as_hash: true
-
-        filter:
-          # Filter which methods Docscribe touches.
-          #
-          # Method id format:
-          #   instance: "MyModule::MyClass#instance_method"
-          #   class:    "MyModule::MyClass.class_method"
-          #
-          # Patterns:
-          # - glob: "*#initialize", "MyApp::*#*"
-          # - regex: "/^MyApp::.*#(foo|bar)$/"
-          #
-          # Semantics:
-          # - scopes / visibilities act as allow-lists
-          # - exclude wins
-          # - if include is empty => include everything (subject to allow-lists)
-          visibilities: ["public", "protected", "private"]
-          scopes: ["instance", "class"]
-          include: []
-          exclude: []
-
-          files:
-            # Filter which files Docscribe processes (paths are matched relative
-            # to the project root).
-            #
-            # Tips:
-            # - Use directory shorthand to exclude a whole directory:
-            #     exclude: ["spec"]
-            # - Or use globs:
-            #     exclude: ["spec/**/*.rb", "vendor/**/*.rb"]
-            include: []
-            exclude: ["spec"]
-
-        plugins:
-          # Load custom plugins by path or gem name.
-          #
-          # Each entry is passed to `require`. Registration happens inside
-          # the required file via Docscribe::Plugin::Registry.register.
-          #
-          # Example:
-          #   require:
-          #     - ./docscribe_plugins
-          #     - docscribe-rails-associations
-          require: []
-
         rbs:
-          # Optional: use RBS signatures to improve @param / @return types.
-          #
-          # CLI equivalent:
-          # bundle exec docscribe -a --rbs --sig-dir sig lib
-          #
-          # Under Bundler, you may need `gem "rbs"` in your Gemfile (or a
-          # Gemfile that includes it), otherwise `require "rbs"` may fail and
-          # Docscribe will fall back to inference.
+          # Use RBS signatures for better types (requires `gem "rbs"`)
           enabled: false
-
-          # Signature directories (repeatable via --sig-dir).
           sig_dirs: ["sig"]
-
-          # If true, simplify generic types:
-          # - Hash<Symbol, String> => Hash
-          # - Array<Integer>       => Array
-          collapse_generics: false
-          # Auto-discover RBS collection from rbs_collection.lock.yaml.
-          # Equivalent to --rbs-collection CLI flag.
-          # Requires `bundle exec rbs collection install` to have been run.
-          #
-          collection: false
+          collapse_generics: false            # Hash<Symbol, String> => Hash
+          collection: false                   # auto-discover from rbs_collection.lock.yaml
 
         sorbet:
-          # Optional: use Sorbet signatures from inline `sig` declarations and
-          # RBI files to improve @param / @return types.
-          #
-          # CLI equivalent:
-          # bundle exec docscribe -a --sorbet --rbi-dir sorbet/rbi lib
-          #
-          # Sorbet resolution order is:
-          # 1. inline `sig` in the current source file
-          # 2. RBI files
-          # 3. RBS
-          # 4. AST inference
+          # Use Sorbet inline sigs and RBI files for better types
           enabled: false
-
-          # RBI directories scanned recursively for `.rbi` files
-          # (repeatable via --rbi-dir).
           rbi_dirs: ["sorbet/rbi", "rbi"]
-
-          # If true, simplify generic types:
-          # - Hash<Symbol, String> => Hash
-          # - Array<Integer>       => Array
           collapse_generics: false
+
+        plugins:
+          # Load custom plugins
+          # Example:
+          #   require:
+          #     - ./docscribe_plugins
+          #     - docscribe-rails-associations
+          require: []
       YAML
     end
   end

data/lib/docscribe/infer/returns.rb

@@ -24,7 +24,9 @@ module Docscribe
         return FALLBACK_TYPE unless root && %i[def defs].include?(root.type)
 
         body = root.children.last
-        last_expr_type(body, fallback_type: FALLBACK_TYPE, nil_as_optional: true) || FALLBACK_TYPE
+        local_var_types = build_local_variable_types(body)
+        last_expr_type(body, fallback_type: FALLBACK_TYPE, nil_as_optional: true,
+                             local_var_types: local_var_types) || FALLBACK_TYPE
       rescue Parser::SyntaxError
         FALLBACK_TYPE
       end
@@ -43,7 +45,9 @@ module Docscribe
 
         return FALLBACK_TYPE unless body
 
-        last_expr_type(body, fallback_type: FALLBACK_TYPE, nil_as_optional: true) || FALLBACK_TYPE
+        local_var_types = build_local_variable_types(body)
+        last_expr_type(body, fallback_type: FALLBACK_TYPE, nil_as_optional: true,
+                             local_var_types: local_var_types) || FALLBACK_TYPE
       end
 
       # Return a structured return-type spec for a method node.
@@ -70,11 +74,16 @@ module Docscribe
         spec = { normal: FALLBACK_TYPE, rescues: [] }
         return spec unless body
 
+        local_var_types = build_local_variable_types(body)
+
         if body.type == :rescue
           main_body = body.children[0]
+          rescue_local_var_types = build_local_variable_types(body)
+          all_local_var_types = rescue_local_var_types || local_var_types
           spec[:normal] =
             last_expr_type(main_body, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
-                                      core_rbs_provider: core_rbs_provider, param_types: param_types) || FALLBACK_TYPE
+                                      core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                      local_var_types: all_local_var_types) || FALLBACK_TYPE
 
           body.children.each do |ch|
             next unless ch.is_a?(Parser::AST::Node) && ch.type == :resbody
@@ -83,19 +92,50 @@ module Docscribe
             exc_names = Raises.exception_names_from_rescue_list(exc_list)
             rtype =
               last_expr_type(rescue_body, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
-                                          core_rbs_provider: core_rbs_provider, param_types: param_types) ||
+                                          core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                          local_var_types: all_local_var_types) ||
               fallback_type
             spec[:rescues] << [exc_names, rtype]
           end
         else
           spec[:normal] =
             last_expr_type(body, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
-                                 core_rbs_provider: core_rbs_provider, param_types: param_types) || FALLBACK_TYPE
+                                 core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                 local_var_types: local_var_types) || FALLBACK_TYPE
         end
 
         spec
       end
 
+      # Resolve a return type from core RBS for a method call.
+      #
+      # @note module_function: when included, also defines #resolve_rbs_return_type (instance visibility: private)
+      # @private
+      # @param [Object] node Param documentation.
+      # @return [String] FALLBACK_TYPE if lookup fails
+      def build_local_variable_types(node)
+        types = {}
+        ASTWalk.walk(node) do |n|
+          case n.type
+          when :lvasgn, :gvasgn, :ivasgn
+            name = n.children[0].to_s
+            value = n.children[1]
+            if value
+              inferred = Literals.type_from_literal(value, fallback_type: FALLBACK_TYPE)
+              types[name] = inferred if inferred && inferred != FALLBACK_TYPE
+            end
+          when :casgn
+            name = n.children[0].to_s
+            value = n.children[2]
+            if value
+              inferred = Literals.type_from_literal(value, fallback_type: FALLBACK_TYPE)
+              types[name] = inferred if inferred && inferred != FALLBACK_TYPE
+            end
+          end
+        end
+        types.empty? ? nil : types
+      end
+
       # Infer the type of the last expression in a node.
       #
       # Supports:
@@ -112,30 +152,37 @@ module Docscribe
       # @param [Boolean] nil_as_optional whether `nil` unions should be rendered as optional types
       # @param [Object, nil] core_rbs_provider optional RBS provider for core type lookup
       # @param [Hash, nil] param_types parameter name -> type map for lvar resolution
+      # @param [nil] local_var_types Param documentation.
       # @return [String, nil]
-      def last_expr_type(node, fallback_type:, nil_as_optional:, core_rbs_provider: nil, param_types: nil)
+      def last_expr_type(node, fallback_type:, nil_as_optional:, core_rbs_provider: nil, param_types: nil,
+                         local_var_types: nil)
         return nil unless node
 
         case node.type
         when :begin
           last_expr_type(node.children.last, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
-                                             core_rbs_provider: core_rbs_provider, param_types: param_types)
+                                             core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                             local_var_types: local_var_types)
 
         when :if
           t = last_expr_type(node.children[1], fallback_type: fallback_type, nil_as_optional: nil_as_optional,
-                                               core_rbs_provider: core_rbs_provider, param_types: param_types)
+                                               core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                               local_var_types: local_var_types)
           e = last_expr_type(node.children[2], fallback_type: fallback_type, nil_as_optional: nil_as_optional,
-                                               core_rbs_provider: core_rbs_provider, param_types: param_types)
+                                               core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                               local_var_types: local_var_types)
           unify_types(t, e, fallback_type: fallback_type, nil_as_optional: nil_as_optional)
 
         when :case
           branches = node.children[1..].compact.flat_map do |child|
             if child.type == :when
               last_expr_type(child.children.last, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
-                                                  core_rbs_provider: core_rbs_provider, param_types: param_types)
+                                                  core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                                  local_var_types: local_var_types)
             else
               last_expr_type(child, fallback_type: fallback_type, nil_as_optional: nil_as_optional,
-                                    core_rbs_provider: core_rbs_provider, param_types: param_types)
+                                    core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                    local_var_types: local_var_types)
             end
           end.compact
 
@@ -150,6 +197,36 @@ module Docscribe
         when :return
           Literals.type_from_literal(node.children.first, fallback_type: fallback_type)
 
+        when :block
+          send_node = node.children[0]
+          if send_node&.type == :send
+            recv = send_node.children[0]
+            meth = send_node.children[1]
+
+            if core_rbs_provider && recv&.type == :lvar
+              lvar_name = recv.children.first
+              recv_type = nil
+              recv_type = local_var_types[lvar_name.to_s] if local_var_types && lvar_name
+              recv_type = param_types[lvar_name.to_s] if !recv_type && param_types && lvar_name
+              if recv_type
+                rbs_type = resolve_rbs_return_type(recv_type, meth, core_rbs_provider)
+                return rbs_type unless rbs_type == FALLBACK_TYPE
+              end
+            elsif core_rbs_provider && recv&.type == :send
+              inner_type = last_expr_type(recv, fallback_type: nil, nil_as_optional: false,
+                                                core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                                local_var_types: local_var_types)
+              if inner_type
+                rbs_type = resolve_rbs_return_type(inner_type, meth, core_rbs_provider)
+                return rbs_type unless rbs_type == FALLBACK_TYPE
+              end
+            end
+          end
+
+          last_expr_type(node.children[2], fallback_type: fallback_type, nil_as_optional: nil_as_optional,
+                                           core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                           local_var_types: local_var_types)
+
         when :send
           recv = node.children[0]
           meth = node.children[1]
@@ -158,20 +235,22 @@ module Docscribe
           if core_rbs_provider && recv&.type == :send
             # Chained call: arg.to_i.positive?
             inner_type = last_expr_type(recv, fallback_type: nil, nil_as_optional: false,
-                                              core_rbs_provider: core_rbs_provider, param_types: param_types)
+                                              core_rbs_provider: core_rbs_provider, param_types: param_types,
+                                              local_var_types: local_var_types)
             if inner_type
               rbs_type = resolve_rbs_return_type(inner_type, meth, core_rbs_provider)
               return rbs_type unless rbs_type == FALLBACK_TYPE
             end
+
           elsif core_rbs_provider && recv&.type == :lvar
-            # Direct call: arg.positive?
+            # Direct call on local variable: p1.positive? or admins.any?
             lvar_name = recv.children.first
-            if lvar_name && param_types
-              recv_type = param_types[lvar_name.to_s]
-              if recv_type
-                rbs_type = resolve_rbs_return_type(recv_type, meth, core_rbs_provider)
-                return rbs_type unless rbs_type == FALLBACK_TYPE
-              end
+            recv_type = nil
+            recv_type = local_var_types[lvar_name.to_s] if local_var_types && lvar_name
+            recv_type = param_types[lvar_name.to_s] if !recv_type && param_types && lvar_name
+            if recv_type
+              rbs_type = resolve_rbs_return_type(recv_type, meth, core_rbs_provider)
+              return rbs_type unless rbs_type == FALLBACK_TYPE
             end
           end
 
@@ -182,14 +261,13 @@ module Docscribe
         end
       end
 
-      # Resolve a return type from core RBS for a method call.
+      # Method documentation.
       #
       # @note module_function: when included, also defines #resolve_rbs_return_type (instance visibility: private)
-      # @private
-      # @param [String] container_type e.g. "Numeric", "String"
-      # @param [Symbol] method_name e.g. :positive?
-      # @param [Object, nil] core_rbs_provider RBS provider
-      # @return [String] FALLBACK_TYPE if lookup fails
+      # @param [Object] container_type Param documentation.
+      # @param [Object] method_name Param documentation.
+      # @param [Object] core_rbs_provider Param documentation.
+      # @return [Object]
       def resolve_rbs_return_type(container_type, method_name, core_rbs_provider)
         return FALLBACK_TYPE unless core_rbs_provider
 

data/lib/docscribe/inline_rewriter/doc_block.rb

@@ -65,11 +65,20 @@ module Docscribe
       # @param [Array<String>] missing_lines generated tag lines to add
       # @param [Boolean] sort_tags whether sortable tags should be reordered
       # @param [Array<String>] tag_order configured sortable tag order
+      # @param [Hash] filter_existing Param documentation.
       # @return [Array<String>]
-      def merge(existing_lines, missing_lines:, sort_tags:, tag_order:)
+      def merge(existing_lines, missing_lines:, sort_tags:, tag_order:, filter_existing: {})
         existing_entries = parse(existing_lines, tag_order: tag_order)
         missing_entries = parse_generated(missing_lines, tag_order: tag_order)
 
+        filter_param_names = filter_existing[:param_names] || []
+        filter_return = !!filter_existing[:return]
+
+        existing_entries = existing_entries.reject do |e|
+          (e.kind == :tag && e.tag == 'param' && filter_param_names.include?(e.subject)) ||
+            (e.kind == :tag && e.tag == 'return' && filter_return)
+        end
+
         entries = existing_entries + missing_entries
         entries = sort(entries, tag_order: tag_order) if sort_tags
 

data/lib/docscribe/inline_rewriter/doc_builder.rb

@@ -228,10 +228,11 @@ module Docscribe
       # @param [Object, nil] signature_provider
       # @param [nil] core_rbs_provider Param documentation.
       # @param [nil] param_types Param documentation.
+      # @param [nil] strategy Param documentation.
       # @raise [StandardError]
       # @return [Hash]
       def build_missing_merge_result(insertion, existing_lines:, config:, signature_provider: nil,
-                                     core_rbs_provider: nil, param_types: nil)
+                                     core_rbs_provider: nil, param_types: nil, strategy: nil)
         node = insertion.node
         name = SourceHelpers.node_name(node)
         return { lines: [], reasons: [] } unless name
@@ -283,10 +284,22 @@ module Docscribe
 
           all_params&.each do |pl|
             pname = extract_param_name_from_param_line(pl)
-            next if pname.nil? || info[:param_names].include?(pname)
-
-            lines << "#{pl}\n"
-            reasons << { type: :missing_param, message: "missing @param #{pname}", extra: { param: pname } }
+            next unless pname
+
+            if !info[:param_names].include?(pname)
+              lines << "#{pl}\n"
+              reasons << { type: :missing_param, message: "missing @param #{pname}", extra: { param: pname } }
+            elsif external_sig && info[:param_types][pname]
+              new_type = extract_param_type_from_param_line(pl)
+              if new_type && info[:param_types][pname] != new_type
+                lines << "#{pl}\n" unless strategy == :safe
+                reasons << {
+                  type: :updated_param,
+                  message: "updated @param #{pname} from #{info[:param_types][pname]} to #{new_type}",
+                  extra: { param: pname }
+                }
+              end
+            end
           end
         end
 
@@ -301,9 +314,17 @@ module Docscribe
           end
         end
 
-        if config.emit_return_tag?(scope, visibility) && !info[:has_return]
-          lines << "#{indent}# @return [#{normal_type}]\n"
-          reasons << { type: :missing_return, message: 'missing @return' }
+        if config.emit_return_tag?(scope, visibility)
+          if !info[:has_return]
+            lines << "#{indent}# @return [#{normal_type}]\n"
+            reasons << { type: :missing_return, message: 'missing @return' }
+          elsif external_sig && info[:return_type] && info[:return_type] != normal_type
+            lines << "#{indent}# @return [#{normal_type}]\n" unless strategy == :safe
+            reasons << {
+              type: :updated_return,
+              message: "updated @return from #{info[:return_type]} to #{normal_type}"
+            }
+          end
         end
 
         if config.emit_rescue_conditional_returns? && !info[:has_return]
@@ -341,7 +362,9 @@ module Docscribe
       # @return [Hash] parsed tag info
       def parse_existing_doc_tags(lines)
         param_names = {}
+        param_types = {}
         has_return = false
+        return_type = nil
         has_private = false
         has_protected = false
         has_module_function_note = false
@@ -354,9 +377,17 @@ module Docscribe
           end
           if (pname = extract_param_name_from_param_line(line))
             param_names[pname] = true
+            if (type_match = line.match(/@param\s+\[([^\]]+)\]\s+\S+/) || line.match(/@param\s+\S+\s+\[([^\]]+)\]/))
+              param_types[pname] = type_match[1]
+            end
           end
 
-          has_return ||= line.match?(/^\s*#\s*@return\b/)
+          if line.match?(/^\s*#\s*@return\b/)
+            has_return = true
+            if (m = line.match(/@return\s+\[([^\]]+)\]/))
+              return_type = m[1]
+            end
+          end
           has_private ||= line.match?(/^\s*#\s*@private\b/)
           has_protected ||= line.match?(/^\s*#\s*@protected\b/)
           has_module_function_note ||= line.match?(/^\s*#\s*@note\s+module_function:/)
@@ -366,7 +397,9 @@ module Docscribe
 
         {
           param_names: param_names,
+          param_types: param_types,
           has_return: has_return,
+          return_type: return_type,
           raise_types: raise_types,
           has_private: has_private,
           has_protected: has_protected,
@@ -462,6 +495,19 @@ module Docscribe
                    treat_options_keyword_as_hash: config.treat_options_keyword_as_hash?
                  )
             param_types[pname] = ty
+
+          when :kwoptarg
+            pname, default = *a
+            pname = pname.to_s
+            default_src = default&.loc&.expression&.source
+            ty = external_sig&.param_types&.[](pname) ||
+                 Infer.infer_param_type(
+                   "#{pname}:",
+                   default_src,
+                   fallback_type: config.fallback_type,
+                   treat_options_keyword_as_hash: config.treat_options_keyword_as_hash?
+                 )
+            param_types[pname] = ty
           end
         end
 
@@ -672,6 +718,17 @@ module Docscribe
         nil
       end
 
+      # Method documentation.
+      #
+      # @note module_function: when included, also defines #extract_param_type_from_param_line (instance visibility: private)
+      # @param [Object] line Param documentation.
+      # @return [Object]
+      def extract_param_type_from_param_line(line)
+        if (m = line.match(/@param\s+\[([^\]]+)\]\s+\S+/) || line.match(/@param\s+\S+\s+\[([^\]]+)\]/))
+          m[1]
+        end
+      end
+
       # Build a Plugin::Context from a collected insertion.
       #
       # @note module_function

data/lib/docscribe/inline_rewriter.rb

@@ -83,20 +83,11 @@ module Docscribe
 
         config ||= Docscribe::Config.load
         signature_provider = build_signature_provider(config, code, file.to_s)
-        unless core_rbs_provider
-          if config.respond_to?(:core_rbs_provider)
-            begin
-              core_rbs_provider = config.core_rbs_provider
-            rescue StandardError
-              core_rbs_provider = nil
-            end
-          elsif config.respond_to?(:rbs_provider)
-            begin
-              core_rbs_provider = config.rbs_provider
-            rescue StandardError
-              core_rbs_provider = nil
-            end
-          end
+        begin
+          core_rbs_provider ||= config.core_rbs_provider if config.respond_to?(:core_rbs_provider)
+        rescue StandardError => e
+          warn "Docscribe: failed to load core RBS provider: #{e.message}" if ENV['DOCSCRIBE_DEBUG']
+          core_rbs_provider = nil
         end
 
         collector = Docscribe::InlineRewriter::Collector.new(buffer)
@@ -345,8 +336,14 @@ module Docscribe
             rewriter.remove(range)
           end
 
+          effective_param_types = external_sig&.param_types || DocBuilder.build_param_types_from_node(
+            insertion.node,
+            external_sig: external_sig,
+            config: config
+          )
+
           doc = build_method_doc(insertion, config: config, signature_provider: signature_provider,
-                                            core_rbs_provider: core_rbs_provider, param_types: external_sig&.param_types)
+                                            core_rbs_provider: core_rbs_provider, param_types: effective_param_types)
           return if doc.nil? || doc.empty?
 
           rewriter.insert_before(anchor_bol_range, doc)
@@ -369,7 +366,8 @@ module Docscribe
               config: config,
               signature_provider: signature_provider,
               core_rbs_provider: core_rbs_provider,
-              param_types: external_sig&.param_types
+              param_types: external_sig&.param_types,
+              strategy: strategy
             )
 
             missing_lines = merge_result[:lines]
@@ -397,24 +395,28 @@ module Docscribe
               range = Parser::Source::Range.new(buffer, info[:start_pos], info[:end_pos])
               rewriter.replace(range, new_block)
 
-              reason_specs.each do |reason|
+              if existing_order_changed
                 add_change(
                   changes,
-                  type: reason[:type],
+                  type: :unsorted_tags,
                   insertion: insertion,
                   file: file,
-                  message: reason[:message],
-                  extra: reason[:extra] || {}
+                  message: 'unsorted tags'
                 )
               end
+            end
 
-              if existing_order_changed
+            type_mismatch_reasons = reason_specs.select { |r| %i[updated_param updated_return].include?(r[:type]) }
+
+            if new_block != old_block || type_mismatch_reasons.any?
+              reason_specs.each do |reason|
                 add_change(
                   changes,
-                  type: :unsorted_tags,
+                  type: reason[:type],
                   insertion: insertion,
                   file: file,
-                  message: 'unsorted tags'
+                  message: reason[:message],
+                  extra: reason[:extra] || {}
                 )
               end
             end
@@ -423,7 +425,8 @@ module Docscribe
           end
 
           doc = build_method_doc(insertion, config: config, signature_provider: signature_provider,
-                                            core_rbs_provider: core_rbs_provider, param_types: external_sig&.param_types)
+                                            core_rbs_provider: core_rbs_provider,
+                                            param_types: external_sig&.param_types)
           return if doc.nil? || doc.empty?
 
           rewriter.insert_before(anchor_bol_range, doc)
@@ -790,16 +793,18 @@ module Docscribe
       # @param [Object, nil] signature_provider external signature provider
       # @param [Object, nil] core_rbs_provider RBS core type provider
       # @param [Hash, nil] param_types parameter name -> type map
+      # @param [Object] strategy Param documentation.
       # @return [Hash] result with `:lines` and `:reasons` keys
       def build_missing_method_merge_result(insertion, existing_lines:, config:, signature_provider:,
-                                            core_rbs_provider:, param_types:)
+                                            core_rbs_provider:, param_types:, strategy:)
         DocBuilder.build_missing_merge_result(
           insertion,
           existing_lines: existing_lines,
           config: config,
           signature_provider: signature_provider,
           core_rbs_provider: core_rbs_provider,
-          param_types: param_types
+          param_types: param_types,
+          strategy: strategy
         )
       end
 

data/lib/docscribe/plugin/base/collector_plugin.rb

@@ -41,8 +41,6 @@ module Docscribe
         # - :anchor_node => Parser::AST::Node — node above which to insert doc
         # - :doc         => String — complete doc block including newlines
         #
-        # @param [Parser::AST::Node] ast root AST node of the file
-        # @param [Parser::Source::Buffer] buffer source buffer
         # @param [Object] _ast Param documentation.
         # @param [Object] _buffer Param documentation.
         # @return [Array<Hash>]

data/lib/docscribe/types/rbs/provider.rb

@@ -89,10 +89,27 @@ module Docscribe
         # @param [Symbol] scope
         # @return [Object]
         def definition_for(container:, scope:)
-          type_name = ::RBS::TypeName.parse(absolute_const(container))
+          type_name = parse_type_name(absolute_const(container))
           scope == :class ? @builder.build_singleton(type_name) : @builder.build_instance(type_name)
         end
 
+        # Parse a fully-qualified constant string into an RBS TypeName.
+        #
+        # Uses the lower-level constructor so it works across RBS versions
+        # that may not expose `TypeName.parse`.
+        #
+        # @private
+        # @param [String] string e.g. "::Irb::Autosuggestions"
+        # @return [::RBS::TypeName]
+        def parse_type_name(string)
+          absolute = string.start_with?('::')
+          *path, name = string.delete_prefix('::').split('::').map(&:to_sym)
+          ::RBS::TypeName.new(
+            name: name,
+            namespace: ::RBS::Namespace.new(path: path, absolute: absolute)
+          )
+        end
+
         # Normalize a container name into an absolute constant path.
         #
         # @private

data/lib/docscribe/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docscribe
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.2
 platform: ruby
 authors:
 - unurgunite
@@ -213,7 +213,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.12
 specification_version: 4
 summary: Auto-generate inline YARD documentation for Ruby by analyzing code AST. Supports
   RBS and Sorbet type signatures.