docscribe 1.6.1 → 1.6.2

data/lib/docscribe/types/primitive.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+# NOTE: no top-level `require 'rbs'` here on purpose — the rbs gem is
+# optional (excluded on old rubies via BUNDLE_WITHOUT). It is required
+# lazily in `.load_rbs_core`, which falls back to a hardcoded list when
+# the gem is unavailable.
+#
+# `set` is required eagerly: it is a default gem on all supported rubies
+# and `load_core_primitives` cannot run without it.
+require 'set'
+
+module Docscribe
+  module Types
+    # Dynamic primitive type detection via RBS core + YARD.
+    #
+    # Replaces hardcoded %w[String Integer ...] lists in
+    # Returns and GenericCompatibility with RBS environment inspection.
+    module Primitive
+      module_function
+
+      # Whether token matches alias pattern (lowercase after :: or capitalized not in primitives)
+      #
+      # @note module_function: defines #alias_pattern? (visibility: private)
+      # @param [String] token
+      # @return [Boolean]
+      def alias_pattern?(token)
+        base = normalized_base(token)
+        return true if base =~ /\A[a-z]/ || base.include?('::')
+        return true if base =~ /\A[A-Z]\z/
+
+        !!(base =~ /\A[A-Z][A-Za-z0-9_]*\z/ && !core_primitives.include?(base))
+      end
+
+      # Whether a type string is an alias (contains alias token inside generic)
+      #
+      # @note module_function: defines #alias_type? (visibility: private)
+      # @param [String] type_str
+      # @return [Boolean]
+      def alias_type?(type_str)
+        # Check if any comma-separated inner is alias
+        # For "Array<Elem>" or "MyAlias" etc
+        type_str.split(',').any? { |part| alias_token?(part.strip) }
+      end
+
+      # Whether token is an alias/generic placeholder (Elem, U, ParamTag, MyAlias)
+      # vs primitive. Inverse of primitive?.
+      #
+      # @note module_function: defines #alias_token? (visibility: private)
+      # @param [String] token single type token
+      # @return [Boolean] true if alias
+      def alias_token?(token)
+        base = normalized_base(token)
+        return false if primitive?(base)
+        return true if base =~ /\A[a-z]/ || base.include?('::')
+        return true if base =~ /\A[A-Z]\z/
+
+        !!(base =~ /\A[A-Z][A-Za-z0-9_]*\z/ && !core_primitives.include?(base))
+      end
+
+      # Whether token is a primitive type (String, Integer, etc) vs alias (Elem, U, ParamTag).
+      #
+      # Uses RBS core class declarations + YARD pseudo types (Boolean, void, untyped)
+      # to avoid hardcoding the full list. Falls back to a minimal list if RBS unavailable.
+      #
+      # @note module_function: defines #primitive? (visibility: private)
+      # @param [String] token type token (e.g., "String", "Elem", "ParamTag", "untyped")
+      # @return [Boolean] true if primitive, false if alias/generic placeholder
+      def primitive?(token)
+        base = normalized_base(token)
+        return false if base.empty?
+        return true if %w[untyped void nil].include?(base)
+        # YARD pseudo types that are not real RBS classes but considered primitives
+        return true if %w[Boolean void untyped nil].include?(base)
+
+        core_primitives.include?(base)
+      end
+
+      # @note module_function: defines #normalized_base (visibility: private)
+      # @param [String] token
+      # @return [String]
+      def normalized_base(token)
+        token.split('<').first.split('[').first.strip.delete_suffix('?').strip
+      end
+
+      # All core primitive class/module names from RBS environment (String, Array, etc)
+      # plus YARD primitives. Computed once and cached.
+      #
+      # @note module_function: defines #core_primitives (visibility: private)
+      # @return [Array<String>] primitive names
+      def core_primitives
+        @core_primitives ||= load_core_primitives
+      end
+
+      # Load core primitives from RBS environment. Falls back to minimal hardcoded list
+      # if RBS not available (e.g., in test env without rbs gem).
+      #
+      # @note module_function: defines #load_core_primitives (visibility: private)
+      # @return [Array<String>]
+      def load_core_primitives
+        primitives = Set.new
+        load_yard_primitives(primitives)
+        load_rbs_core(primitives)
+        merge_primitives(primitives)
+        primitives.to_a
+      end
+
+      # @note module_function: defines #load_yard_primitives (visibility: private)
+      # @param [Set<String>] primitives
+      # @return [Set<String>]
+      def load_yard_primitives(primitives)
+        primitives.merge(%w[Boolean void untyped nil true false])
+      end
+
+      # @note module_function: defines #load_rbs_core (visibility: private)
+      # @param [Set<String>] primitives
+      # @raise [LoadError]
+      # @raise [StandardError]
+      # @return [Set<String>]
+      # @return [Set<String>] if LoadError, StandardError
+      def load_rbs_core(primitives)
+        require 'rbs'
+        loader = RBS::EnvironmentLoader.new
+        env = RBS::Environment.new
+        loader.load(env: env)
+        populate_class_decls(env, primitives)
+        populate_interface_decls(env, primitives)
+      rescue LoadError, StandardError
+        primitives.merge(%w[String Integer Float Numeric Symbol Array Hash Range Regexp Proc Method NilClass TrueClass FalseClass BasicObject Kernel Object Class Module IO File Dir Time Date Enumerator
+                            Set Enumerable])
+      end
+
+      # @note module_function: defines #populate_class_decls (visibility: private)
+      # @param [RBS::Environment] env
+      # @param [Set<String>] primitives
+      # @return [void]
+      def populate_class_decls(env, primitives)
+        return unless env.respond_to?(:class_decls)
+
+        env.class_decls.each_key { |k| primitives.merge([k.to_s.split('::').last, k.to_s]) }
+      end
+
+      # @note module_function: defines #populate_interface_decls (visibility: private)
+      # @param [RBS::Environment] env
+      # @param [Set<String>] primitives
+      # @return [void]
+      def populate_interface_decls(env, primitives)
+        return unless env.respond_to?(:interface_decls)
+
+        env.interface_decls.each_key { |k| primitives << k.to_s.split('::').last }
+      end
+
+      # @note module_function: defines #merge_primitives (visibility: private)
+      # @param [Set<String>] primitives
+      # @return [Set<String>]
+      def merge_primitives(primitives)
+        primitives.merge(%w[String Integer Float Numeric Symbol Array Hash Range Regexp Proc Method NilClass TrueClass FalseClass BasicObject Kernel Object])
+      end
+    end
+  end
+end

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

@@ -59,7 +59,7 @@ module Docscribe
           return unless defined?(RubyVM::AbstractSyntaxTree)
 
           parser = ::RBS::Prototype::RBI.new
-          parser.parse(source)
+          parse(parser, source)
           index_decls(parser.decls)
         rescue LoadError
           nil
@@ -68,6 +68,38 @@ module Docscribe
           nil
         end
 
+        # Parse the source with the RBS RBI prototype, suppressing the parser's
+        # "Unexpected type_node" STDERR noise unless DOCSCRIBE_RBS_DEBUG=1.
+        #
+        # @private
+        # @param [::RBS::Prototype::RBI] parser RBI parser instance
+        # @param [String] source source text to parse
+        # @return [void]
+        def parse(parser, source)
+          if ENV['DOCSCRIBE_RBS_DEBUG'] == '1'
+            parser.parse(source)
+          else
+            suppress_rbs_noise { parser.parse(source) }
+          end
+        end
+
+        # Run the block with STDERR discarded. RBS's RBI prototype prints
+        # "Unexpected type_node" directly to STDERR for constructs it doesn't
+        # model (e.g. Herb-typed RBIs); the fallback to `Any` is already handled
+        # by the parser, so the noise is safe to drop. `IO#reopen` needs a real
+        # IO or path, so redirect to File::NULL rather than a StringIO.
+        #
+        # @private
+        # @return [T] the block's return value
+        def suppress_rbs_noise
+          original_stderr = $stderr.dup
+          $stderr.reopen(File::NULL, 'w')
+          yield
+        ensure
+          $stderr.reopen(original_stderr)
+          original_stderr.close
+        end
+
         # Index parsed declarations into the provider lookup table.
         #
         # @private

data/lib/docscribe/types/yard/formatter.rb

@@ -10,24 +10,53 @@ module Docscribe
         class << self
           # @param [Docscribe::Types::Yard::node?] node
           # @return [String]
-          def to_rbs(node) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+          def to_rbs(node)
             return 'untyped' if node.nil?
 
+            rbs_for_node(node) || 'untyped'
+          end
+
+          private
+
+          # @private
+          # @param [Docscribe::Types::Yard::node] node
+          # @return [String, nil]
+          def rbs_for_node(node)
+            simple_type(node) || composite_type(node) || collection_type(node)
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::node] node
+          # @return [String, nil]
+          def simple_type(node)
             case node
             when Named then format_named(node)
-            when Generic then format_generic(node)
+            when Literal then format_literal(node)
+            end
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::node] node
+          # @return [String, nil]
+          def composite_type(node)
+            case node
             when Union then format_union(node)
             when Intersection then format_intersection(node)
             when Optional then format_optional(node)
+            end
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::node] node
+          # @return [String, nil]
+          def collection_type(node)
+            case node
+            when Generic then format_generic(node)
             when Tuple then format_tuple(node)
             when HashMap then format_hash_map(node)
-            when Literal then format_literal(node)
-            else 'untyped'
             end
           end
 
-          private
-
           # @private
           # @param [Docscribe::Types::Yard::Named] node
           # @return [String]

data/lib/docscribe/types/yard/parser.rb

@@ -40,7 +40,7 @@ module Docscribe
         def parse_union
           types = [parse_intersection]
           skip_space
-          while @i < @s.length && @s[@i] == ','
+          while peek == ','
             @i += 1
             skip_space
             types << parse_intersection
@@ -54,7 +54,7 @@ module Docscribe
         def parse_intersection
           types = [parse_optional]
           skip_space
-          while @i < @s.length && @s[@i] == '&'
+          while peek == '&'
             @i += 1
             skip_space
             types << parse_optional
@@ -68,7 +68,7 @@ module Docscribe
         def parse_optional
           type = parse_primary
           skip_space
-          if @i < @s.length && @s[@i] == '?'
+          if peek == '?'
             @i += 1
             Optional.new(type: type)
           else
@@ -96,9 +96,9 @@ module Docscribe
           return Literal.new(value: name) if literal?(name)
 
           skip_space
-          if @i < @s.length && @s[@i] == '<'
+          if peek == '<'
             parse_generic(Named.new(name: name))
-          elsif @i < @s.length && @s[@i] == '{'
+          elsif peek == '{'
             parse_named_hash_map
           else
             Named.new(name: name)
@@ -111,7 +111,7 @@ module Docscribe
         def parse_generic(base)
           @i += 1
           args = parse_generic_args
-          @i += 1 if @i < @s.length && @s[@i] == '>'
+          @i += 1 if peek == '>'
           Generic.new(base: base.name, args: args)
         end
 
@@ -120,7 +120,7 @@ module Docscribe
         def parse_generic_arg
           types = [parse_intersection]
           skip_space
-          while @i < @s.length && @s[@i] == '|'
+          while peek == '|'
             @i += 1
             skip_space
             types << parse_intersection
@@ -134,10 +134,10 @@ module Docscribe
         def parse_generic_args
           args = [] #: Array[untyped]
           skip_space
-          while @i < @s.length && @s[@i] != '>'
+          while peek && peek != '>'
             args << parse_generic_arg
             skip_space
-            next unless @i < @s.length && @s[@i] == ','
+            next unless peek == ','
 
             @i += 1
             skip_space
@@ -150,11 +150,11 @@ module Docscribe
         def parse_tuple
           @i += 1
           types = [] #: Array[untyped]
-          while @i < @s.length && @s[@i] != ')'
+          while peek && peek != ')'
             types << parse_tuple_element
-            @i += 1 and skip_space if @s[@i] == ','
+            @i += 1 and skip_space if peek == ','
           end
-          @i += 1 if @s[@i] == ')'
+          @i += 1 if peek == ')'
           Tuple.new(types: types)
         end
 
@@ -163,7 +163,7 @@ module Docscribe
         def parse_tuple_element
           type = parse_intersection
           skip_space
-          if @i < @s.length && @s[@i] == '?'
+          if peek == '?'
             @i += 1
             Optional.new(type: type)
           else
@@ -176,9 +176,9 @@ module Docscribe
         def parse_hash_map
           @i += 1
           key = parse_union
-          @i += 2 if @s[@i..(@i + 1)] == '=>'
+          @i += 2 if @s[@i, 2] == '=>'
           value = parse_union
-          @i += 1 if @s[@i] == '}'
+          @i += 1 if peek == '}'
           HashMap.new(key_type: key, value_type: value)
         end
 
@@ -192,7 +192,7 @@ module Docscribe
         # @return [Docscribe::Types::Yard::Duck]
         def parse_duck_type
           methods = [] #: Array[String]
-          while @i < @s.length && @s[@i] == '#'
+          while peek == '#'
             @i += 1
             name = scan_name
             methods << name
@@ -205,7 +205,12 @@ module Docscribe
         # @return [String]
         def scan_name
           start = @i
-          @i += 1 while @i < @s.length && name_char?(@s[@i])
+          loop do
+            c = peek
+            break unless c && name_char?(c)
+
+            @i += 1
+          end
           @s[start...@i]
         end
 
@@ -226,13 +231,13 @@ module Docscribe
         # @private
         # @return [void]
         def skip_space
-          @i += 1 while @i < @s.length && @s[@i].match?(/\s/)
+          @i += 1 while peek&.match?(/\s/)
         end
 
         # @private
         # @return [String?]
-        def peek
-          @i < @s.length ? @s[@i] : nil
+        def peek #: String?
+          @s[@i]
         end
       end
     end

data/lib/docscribe/types/yard/validator.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative 'parser'
+
+module Docscribe
+  module Types
+    module Yard
+      # Validates YARD type strings for syntax errors.
+      #
+      # This validator is intentionally lightweight and does not perform
+      # semantic type-existence checks (e.g. `Symbol2l` vs `Symbol`).
+      # Semantic checks are handled by `Docscribe::Validator::TypeMismatchValidator`
+      # which compares a YARD tag against the inferred / RBS type.
+      module Validator
+        module_function
+
+        # Check if a YARD type string is syntactically valid.
+        #
+        # Criteria:
+        # - non-empty after strip
+        # - brackets are balanced (`<>`, `()`, `{}`, `[]`)
+        # - no `,,`, `<>`, `,]` artefacts
+        # - `Yard::Parser` consumes the entire string (catches `Sym bol` leftover)
+        #
+        # @note module_function: defines #valid? (visibility: private)
+        # @param [String, nil] type_str the YARD type string to validate (e.g. "String", "Array<String>", "Sym bol")
+        # @raise [StandardError]
+        # @return [Boolean]
+        # @return [Boolean] if StandardError
+        def valid?(type_str)
+          syntax_valid?(type_str)
+        rescue StandardError
+          false
+        end
+
+        # Strict syntax validation with balanced brackets and full consumption.
+        #
+        # @note module_function: defines #syntax_valid? (visibility: private)
+        # @param [String, nil] type_str
+        # @raise [StandardError]
+        # @return [Boolean]
+        # @return [Boolean] if StandardError
+        def syntax_valid?(type_str)
+          return false if blank_type?(type_str)
+          return false unless balanced_brackets?(type_str)
+          return false if artefact_type?(type_str)
+
+          fully_consumed?(type_str)
+        rescue StandardError
+          false
+        end
+
+        # @note module_function: defines #blank_type? (visibility: private)
+        # @param [String, nil] type_str
+        # @return [Boolean]
+        def blank_type?(type_str)
+          type_str.nil? || type_str.strip.empty?
+        end
+
+        # @note module_function: defines #artefact_type? (visibility: private)
+        # @param [String, nil] type_str
+        # @return [Boolean]
+        def artefact_type?(type_str)
+          return false if type_str.nil?
+
+          type_str.include?(',,') || type_str.include?('<>') || type_str.include?(',]')
+        end
+
+        # Check balanced brackets for `<>`, `()`, `{}`, `[]`.
+        #
+        # @note module_function: defines #balanced_brackets? (visibility: private)
+        # @param [String, nil] type_str
+        # @return [Boolean]
+        def balanced_brackets?(type_str)
+          return false if type_str.nil?
+
+          stack = [] #: Array[String]
+          pairs = { '>' => '<', ')' => '(', '}' => '{', ']' => '[' }
+          opens = pairs.values
+
+          type_str.each_char do |ch|
+            return false unless process_bracket_char?(ch, stack, pairs, opens)
+          end
+
+          stack.empty?
+        end
+
+        # @note module_function: defines #process_bracket_char? (visibility: private)
+        # @param [String] char
+        # @param [Array<String>] stack
+        # @param [Hash<String, String>] pairs
+        # @param [Array<String>] opens
+        # @return [Boolean]
+        def process_bracket_char?(char, stack, pairs, opens)
+          if opens.include?(char)
+            stack << char
+          elsif pairs.key?(char)
+            return false if stack.empty? || stack.pop != pairs[char]
+          end
+          true
+        end
+
+        # Whether `Yard::Parser` consumes the entire string.
+        #
+        # Catches cases like `Sym bol` where parser would return `Sym` and
+        # leave ` bol` unconsumed.
+        #
+        # @note module_function: defines #fully_consumed? (visibility: private)
+        # @param [String, nil] type_str
+        # @raise [StandardError]
+        # @return [Boolean]
+        # @return [Boolean] if StandardError
+        def fully_consumed?(type_str)
+          return false if type_str.nil?
+
+          stripped = type_str.strip
+          parser = Parser.new(stripped)
+          node = parser.parse
+          return false unless node
+
+          idx = parser.instance_variable_get(:@i)
+          # `Parser#parse` calls `skip_space` before and after `parse_union`,
+          # so `idx` should be at the end if fully consumed.
+          idx == stripped.length
+        rescue StandardError
+          false
+        end
+      end
+    end
+  end
+end