docscribe 1.5.0 → 1.5.1

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'pathname'
+require 'yaml'
 require 'docscribe/types/signature'
 require 'docscribe/types/rbs/type_formatter'
 require 'docscribe/types/rbs/collection_loader'
@@ -42,7 +43,7 @@ module Docscribe
         # @param [Symbol, String] name method name
         # @raise [::RBS::BaseError]
         # @raise [StandardError]
-        # @return [Docscribe::Types::MethodSignature, nil] if StandardError
+        # @return [Docscribe::Types::MethodSignature, nil]
         # @return [nil] if ::RBS::BaseError
         # @return [nil] if StandardError
         def signature_for(container:, scope:, name:)
@@ -105,21 +106,91 @@ module Docscribe
         # @param [Array<String>] collection_dirs RBS collection directories
         # @raise [::RBS::BaseError]
         # @raise [StandardError]
+        # @return [RBS::Environment]
         # @return [RBS::Environment] if ::RBS::BaseError
-        # @return [Object] if ::RBS::BaseError
         def try_with_fallback_build_env(all_dirs, collection_dirs)
-          build_env(all_dirs)
+          # First attempt: load core types + all dirs (sig + collection).
+          # If duplicate declarations occur (stdlib gem in both `library: 'rbs'`
+          # and collection), retry with individual collection gem dirs,
+          # skipping those already provided by the rbs stdlib.
+          build_env_with_collection(all_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
+          warn "Docscribe: RBS collection error (#{e.class}), dropping collection dirs. " \
+               'Set DOCSCRIBE_RBS_DEBUG=1 for details.'
           build_env(@sig_dirs)
         end
 
+        # Build the environment, handling potential duplicate declarations
+        # between rbs stdlib and collection gems.
+        #
+        # @private
+        # @param [Array<String>] all_dirs combined sig and collection dirs
+        # @param [Array<String>] collection_dirs RBS collection directories
+        # @return [RBS::Environment]
+        def build_env_with_collection(all_dirs, collection_dirs)
+          loader = ::RBS::EnvironmentLoader.new
+          loader.add(library: 'rbs') # steep:ignore
+          load_stdlib_libraries!(loader)
+          add_dirs_to_loader!(loader, all_dirs, collection_dirs)
+          env = ::RBS::Environment.from_loader(loader).resolve_type_names
+          @builder = ::RBS::DefinitionBuilder.new(env: env)
+          env
+        end
+
+        # Add directories to the loader, handling collection dirs separately.
+        #
+        # @private
+        # @param [RBS::EnvironmentLoader] loader
+        # @param [Array<String>] all_dirs
+        # @param [Array<String>] collection_dirs
+        # @return [void]
+        def add_dirs_to_loader!(loader, all_dirs, collection_dirs)
+          stdlib = stdlib_gem_names
+          all_dirs.each do |dir|
+            path = Pathname(dir)
+            next unless path.directory?
+
+            if collection_dirs.include?(dir)
+              add_collection_gem_dirs(loader, path, stdlib)
+            else
+              loader.add(path: path)
+            end
+          end
+        end
+
+        # Add individual collection gem directories to the loader.
+        #
+        # @private
+        # @param [RBS::EnvironmentLoader] loader
+        # @param [Pathname] path
+        # @param [Array<String>] stdlib
+        # @return [void]
+        def add_collection_gem_dirs(loader, path, stdlib)
+          path.children.each do |child|
+            next unless child.directory?
+            next if stdlib.include?(child.basename.to_s)
+
+            loader.add(path: child)
+          end
+        end
+
+        # Names of stdlib gems bundled with the `rbs` gem.
+        #
+        # @private
+        # @raise [StandardError]
+        # @return [Array<String>]
+        # @return [Array] if StandardError
+        def stdlib_gem_names
+          rbs_spec = Gem::Specification.find_by_name('rbs')
+          stdlib_dir = File.join(rbs_spec.gem_dir, 'stdlib')
+          Dir.children(stdlib_dir)
+        rescue StandardError
+          []
+        end
+
         # Build an RBS environment from the given directories.
         #
         # @private
@@ -127,8 +198,8 @@ module Docscribe
         # @return [RBS::Environment]
         def build_env(dirs)
           loader = ::RBS::EnvironmentLoader.new
-          # Load core types transitively
           loader.add(library: 'rbs') # steep:ignore
+          load_stdlib_libraries!(loader)
 
           dirs.each do |dir|
             path = Pathname(dir)
@@ -140,6 +211,43 @@ module Docscribe
           env
         end
 
+        # Load stdlib RBS libraries declared in rbs_collection.lock.yaml.
+        #
+        # Without this, RBS types defined in user sig/ files (e.g. UNIXSocket)
+        # fail to resolve and the entire RBS environment breaks, causing all
+        # type lookups to silently fall back to inference.
+        #
+        # @private
+        # @param [RBS::EnvironmentLoader] loader
+        # @raise [StandardError]
+        # @return [void]
+        # @return [nil] if StandardError
+        def load_stdlib_libraries!(loader)
+          lock_path = File.join(Dir.pwd, 'rbs_collection.lock.yaml')
+          return unless File.exist?(lock_path)
+
+          lock = YAML.safe_load_file(lock_path) # steep:ignore
+          (lock['gems'] || []).each { |gem| add_stdlib_gem(loader, gem) }
+        rescue StandardError => e
+          warn "Docscribe: Failed to parse rbs_collection.lock.yaml: #{e.message}"
+        end
+
+        # Add a single stdlib gem from the lock file to the loader.
+        #
+        # @private
+        # @param [RBS::EnvironmentLoader] loader
+        # @param [Object] gem gem entry from rbs_collection.lock.yaml
+        # @raise [StandardError]
+        # @return [void]
+        # @return [nil] if StandardError
+        def add_stdlib_gem(loader, gem)
+          return unless gem.is_a?(Hash) && gem.dig('source', 'type') == 'stdlib'
+
+          loader.add(library: gem['name']) # steep:ignore
+        rescue StandardError => e
+          warn "Docscribe: Failed to load stdlib RBS library '#{gem['name']}': #{e.message}"
+        end
+
         # Build the appropriate instance or singleton definition for a container.
         #
         # @private
@@ -147,7 +255,10 @@ module Docscribe
         # @param [Symbol] scope :instance or :class
         # @return [RBS::Definition, nil]
         def definition_for(container:, scope:)
+          container = container.sub(/\[.*\]/, '').sub(/<.*>/, '')
           type_name = parse_type_name(absolute_const(container))
+          return nil unless @builder&.env&.type_name?(type_name)
+
           scope == :class ? @builder&.build_singleton(type_name) : @builder&.build_instance(type_name)
         end
 
@@ -311,13 +422,12 @@ module Docscribe
           end
         end
 
-        # Print one debug warning per provider instance when debugging is enabled.
+        # Print one warning per provider instance (avoiding repeated spam).
         #
         # @private
         # @param [String] msg warning message text
         # @return [void]
         def warn_once(msg)
-          return unless ENV['DOCSCRIBE_RBS_DEBUG'] == '1'
           return if @warned
 
           @warned = true

data/lib/docscribe/types/sorbet/base_provider.rb

@@ -18,10 +18,12 @@ module Docscribe
         # Initialize
         #
         # @param [Boolean] collapse_generics whether generic container details
+        # @param [Boolean] collapse_object_generics collapse Object generics
         # @return [void]
-        def initialize(collapse_generics: false)
+        def initialize(collapse_generics: false, collapse_object_generics: false)
           require 'rbs'
           @collapse_generics = !!collapse_generics
+          @collapse_object_generics = !!collapse_object_generics
           @index = {}
           @warned = false
         end
@@ -50,7 +52,7 @@ module Docscribe
         # @raise [::RBS::BaseError]
         # @raise [SyntaxError]
         # @raise [StandardError]
-        # @return [void] if ::RBS::BaseError, SyntaxError, StandardError
+        # @return [void]
         # @return [nil] if LoadError
         # @return [nil] if ::RBS::BaseError, SyntaxError, StandardError
         def load_from_string(source, label:)
@@ -210,7 +212,8 @@ module Docscribe
         def format_type(type)
           Docscribe::Types::RBS::TypeFormatter.to_yard(
             type,
-            collapse_generics: @collapse_generics
+            collapse_generics: @collapse_generics,
+            collapse_object_generics: @collapse_object_generics
           )
         end
 
@@ -220,7 +223,7 @@ module Docscribe
         # @param [String] name method name
         # @return [String]
         def normalize_container(name)
-          name.to_s.delete_prefix('::')
+          name.to_s.delete_prefix('::').sub(/\[.*\]/, '').sub(/<.*>/, '')
         end
 
         # Print one debug warning per provider instance when debugging is enabled.

data/lib/docscribe/types/sorbet/rbi_provider.rb

@@ -16,9 +16,10 @@ module Docscribe
         #
         # @param [Array<String>] rbi_dirs directories scanned recursively for
         # @param [Boolean] collapse_generics whether generic container types
+        # @param [Boolean] collapse_object_generics collapse Object generics
         # @return [void]
-        def initialize(rbi_dirs:, collapse_generics: false)
-          super(collapse_generics: collapse_generics)
+        def initialize(rbi_dirs:, collapse_generics: false, collapse_object_generics: false)
+          super(collapse_generics: collapse_generics, collapse_object_generics: collapse_object_generics)
 
           Array(rbi_dirs).each do |dir|
             path = Pathname(dir)

data/lib/docscribe/types/sorbet/source_provider.rb

@@ -15,9 +15,10 @@ module Docscribe
         # @param [String] source Ruby source containing inline `sig` declarations
         # @param [String] file source label used in diagnostics/debug warnings
         # @param [Boolean] collapse_generics whether generic container types
+        # @param [Boolean] collapse_object_generics collapse Object generics
         # @return [void]
-        def initialize(source:, file:, collapse_generics: false)
-          super(collapse_generics: collapse_generics)
+        def initialize(source:, file:, collapse_generics: false, collapse_object_generics: false)
+          super(collapse_generics: collapse_generics, collapse_object_generics: collapse_object_generics)
           load_from_string(source, label: file)
         end
       end

data/lib/docscribe/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docscribe
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.1
 platform: ruby
 authors:
 - unurgunite
@@ -151,12 +151,14 @@ dependencies:
         version: 0.9.38
 executables:
 - docscribe
+- docscribe-client
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
 - exe/docscribe
+- exe/docscribe-client
 - lib/docscribe.rb
 - lib/docscribe/cli.rb
 - lib/docscribe/cli/check_for_comments.rb
@@ -170,6 +172,7 @@ files:
 - lib/docscribe/cli/options.rb
 - lib/docscribe/cli/rbs_gen.rb
 - lib/docscribe/cli/run.rb
+- lib/docscribe/cli/server.rb
 - lib/docscribe/cli/sigs.rb
 - lib/docscribe/cli/update_types.rb
 - lib/docscribe/config.rb
@@ -197,6 +200,7 @@ files:
 - lib/docscribe/inline_rewriter/doc_builder.rb
 - lib/docscribe/inline_rewriter/source_helpers.rb
 - lib/docscribe/inline_rewriter/tag_sorter.rb
+- lib/docscribe/lru_cache.rb
 - lib/docscribe/parsing.rb
 - lib/docscribe/plugin.rb
 - lib/docscribe/plugin/base/collector_plugin.rb
@@ -204,6 +208,7 @@ files:
 - lib/docscribe/plugin/context.rb
 - lib/docscribe/plugin/registry.rb
 - lib/docscribe/plugin/tag.rb
+- lib/docscribe/server.rb
 - lib/docscribe/types/provider_chain.rb
 - lib/docscribe/types/rbs/collection_loader.rb
 - lib/docscribe/types/rbs/provider.rb
@@ -225,7 +230,7 @@ metadata:
   changelog_uri: https://github.com/unurgunite/docscribe/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message: |
-  You installed docscribe 1.5.0. Your future self (and your team) thank you.
+  You installed docscribe 1.5.1. Your future self (and your team) thank you.
 
     $ docscribe --help