docscribe 1.3.1 → 1.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 911fd61018509316b42bf5a799232d24be36cb653d5997c4e170dab5db028884
-  data.tar.gz: 4ce0e7f0cc78c6b94ce366cb464726e083a6050a42f835e35995c378072507e6
+  metadata.gz: 755d272674fe454b80cc008acb50a879da920def321442cdc8cdd7c450b91f52
+  data.tar.gz: 92aa2320a36162272acfa2b430bfa9cccf5a4582770885a996bc61d7a4198bb6
 SHA512:
-  metadata.gz: 107a67dd5c484b840ba5ab85918ec25d53b0ce4adda13e4ef612d3bfa99d4201e82b474cd636f79a60e5e40e5cbaeb8e15c899939b5e74df14f397f4188b4168
-  data.tar.gz: 9cac2bb4b0c37b29707f0d6beec99987ab8d0f3d9327b3f44e9684816694e74fced394d88fc493ee6f5dc19ce07b82fc295e38f9c0273faad09976d125103a9e
+  metadata.gz: 9268725904b6644b4d46a89c72cda271c4d1b5fedc5066396af1515fa955fecb864fad10406db81582391f81d5265595c7c2bb6fe5793bfc1c7b465395937577
+  data.tar.gz: e8012b3c09ec75e8bd7bbed32f51b297edb2d081b65b2bdf849667e1c7cdb5469862697ddc060c8194b4bf08cc671cb61b6b94507ca382841745e27923963513

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?
@@ -53,7 +53,7 @@ module Docscribe
             require 'docscribe/types/rbs/collection_loader'
             collection_path = Docscribe::Types::RBS::CollectionLoader.resolve
             if collection_path
-              raw['rbs']['sig_dirs'] = Array(raw['rbs']['sig_dirs']) + [collection_path]
+              raw['rbs']['collection_dirs'] = Array(raw['rbs']['collection_dirs']) + [collection_path]
             else
               warn 'Docscribe: rbs_collection.lock.yaml not found or collection not installed. ' \
                    'Run `bundle exec rbs collection install` first.'

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

@@ -62,6 +62,7 @@ module Docscribe
         'enabled' => false,
         'collection' => false,
         'sig_dirs' => ['sig'],
+        'collection_dirs' => [],
         'collapse_generics' => false
       },
       'sorbet' => {

data/lib/docscribe/config/rbs.rb

@@ -17,6 +17,7 @@ module Docscribe
         require 'docscribe/types/rbs/provider'
         Docscribe::Types::RBS::Provider.new(
           sig_dirs: rbs_sig_dirs,
+          collection_dirs: rbs_collection_dirs,
           collapse_generics: rbs_collapse_generics?
         )
       rescue LoadError
@@ -73,6 +74,18 @@ module Docscribe
       Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map(&:to_s)
     end
 
+    # RBS collection directories (auto-discovered from rbs_collection.lock.yaml).
+    #
+    # Loaded separately from user sig_dirs so that collection-related
+    # RBS environment errors (e.g. duplicate declarations against core
+    # stdlib types) do not silence all RBS lookups.
+    #
+    # @private
+    # @return [Array<String>]
+    def rbs_collection_dirs
+      Array(raw.dig('rbs', 'collection_dirs')).map(&:to_s)
+    end
+
     # Whether generic RBS types should be collapsed to simpler container names.
     #
     # Examples:

data/lib/docscribe/config/template.rb

@@ -86,6 +86,7 @@ module Docscribe
           # Use RBS signatures for better types (requires `gem "rbs"`)
           enabled: false
           sig_dirs: ["sig"]
+          collection_dirs: []                 # auto-discovered from --rbs-collection
           collapse_generics: false            # Hash<Symbol, String> => Hash
           collection: false                   # auto-discover from rbs_collection.lock.yaml
 

data/lib/docscribe/inline_rewriter/doc_builder.rb

@@ -289,10 +289,10 @@ module Docscribe
             if !info[:param_names].include?(pname)
               lines << "#{pl}\n"
               reasons << { type: :missing_param, message: "missing @param #{pname}", extra: { param: pname } }
-            elsif info[:param_types][pname] && strategy != :safe
+            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"
+                lines << "#{pl}\n" unless strategy == :safe
                 reasons << {
                   type: :updated_param,
                   message: "updated @param #{pname} from #{info[:param_types][pname]} to #{new_type}",
@@ -318,8 +318,8 @@ module Docscribe
           if !info[:has_return]
             lines << "#{indent}# @return [#{normal_type}]\n"
             reasons << { type: :missing_return, message: 'missing @return' }
-          elsif info[:return_type] && info[:return_type] != normal_type && strategy != :safe
-            lines << "#{indent}# @return [#{normal_type}]\n"
+          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}"

data/lib/docscribe/inline_rewriter.rb

@@ -395,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

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

@@ -15,16 +15,21 @@ module Docscribe
       # the pipeline can stay independent of the underlying signature source.
       class Provider
         # @param [Array<String>] sig_dirs directories containing `.rbs` files
+        # @param [Array<String>] collection_dirs RBS collection directories
+        #   (loaded separately; on error they are silently dropped and only
+        #   user sig_dirs are used)
         # @param [Boolean] collapse_generics whether generic container types
         #   should be simplified during formatting
         # @return [Object]
-        def initialize(sig_dirs:, collapse_generics: false)
+        def initialize(sig_dirs:, collection_dirs: [], collapse_generics: false)
           require 'rbs'
           @sig_dirs = Array(sig_dirs).map(&:to_s)
+          @collection_dirs = Array(collection_dirs).map(&:to_s)
           @collapse_generics = !!collapse_generics
           @env = nil
           @builder = nil
           @warned = false
+          @collection_dropped = false
         end
 
         # Look up a normalized method signature from loaded RBS definitions.
@@ -64,22 +69,48 @@ module Docscribe
 
         # Lazily load and resolve the RBS environment.
         #
+        # Tries to load collection dirs together with user sig_dirs.
+        # If the combined environment raises a load error (e.g. duplicate
+        # declarations between collection and core stdlib types), collection
+        # dirs are dropped and only user sig_dirs are used.
+        #
         # @private
+        # @raise [::RBS::BaseError]
+        # @raise [StandardError]
         # @return [void]
         def load_env!
           return if @env && @builder
 
+          @env = build_env(@sig_dirs + @collection_dirs)
+        rescue ::RBS::BaseError => e
+          raise unless @collection_dirs.any? && !@collection_dropped
+
+          @collection_dropped = true
+          if ENV['DOCSCRIBE_RBS_DEBUG'] == '1'
+            warn "Docscribe: RBS collection error (#{e.class}), dropping collection dirs. " \
+                 'Set DOCSCRIBE_RBS_DEBUG=1 for details.'
+          end
+          @env = build_env(@sig_dirs)
+        end
+
+        # Build an RBS environment from the given directories.
+        #
+        # @private
+        # @param [Array<String>] dirs
+        # @return [::RBS::Environment]
+        def build_env(dirs)
           loader = ::RBS::EnvironmentLoader.new
           # Load core types transitively
           loader.add(library: 'rbs')
 
-          @sig_dirs.each do |dir|
+          dirs.each do |dir|
             path = Pathname(dir)
             loader.add(path: path) if path.directory?
           end
 
-          @env = ::RBS::Environment.from_loader(loader).resolve_type_names
-          @builder = ::RBS::DefinitionBuilder.new(env: @env)
+          env = ::RBS::Environment.from_loader(loader).resolve_type_names
+          @builder = ::RBS::DefinitionBuilder.new(env: env)
+          env
         end
 
         # Build the appropriate instance or singleton definition for a container.
@@ -89,10 +120,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.1'
+  VERSION = '1.3.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docscribe
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.3.3
 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.