typespec_from_serializers 0.1.1 → 0.2.1

data/lib/typespec_from_serializers/sorbet.rb

@@ -0,0 +1,461 @@
+# frozen_string_literal: true
+
+module TypeSpecFromSerializers
+  # Public: Sorbet integration for type inference.
+  #
+  # This module provides optional integration with Sorbet's runtime type system
+  # and RBI files. It can extract type information from:
+  # 1. Runtime signatures (T::Utils.signature_for_method)
+  # 2. RBI files generated by Tapioca (in sorbet/rbi/ directory)
+  #
+  # The module gracefully degrades when sorbet-runtime is not present, making
+  # Sorbet integration completely optional with zero configuration required.
+  module Sorbet
+  module_function
+
+    # Public: Check if Sorbet runtime is available.
+    #
+    # Returns true if sorbet-runtime gem is loaded and the necessary APIs
+    # are available for type extraction.
+    #
+    # Returns Boolean
+    def available?
+      !!(defined?(T::Utils) && T::Utils.respond_to?(:signature_for_method))
+    end
+
+    # Public: Get the RBI directory path.
+    #
+    # Returns Pathname or nil if directory doesn't exist or can't be accessed
+    def rbi_path
+      return @rbi_path if defined?(@rbi_path)
+
+      @rbi_path = begin
+        TypeSpecFromSerializers.rbi_dir.then { |path| path if path.exist? && path.directory? }
+      rescue
+        nil
+      end
+    end
+
+    # Public: Check if RBI files are available for parsing.
+    #
+    # Returns true if sorbet/rbi/ directory exists (typical Tapioca setup).
+    #
+    # Returns Boolean
+    def rbi_available?
+      !rbi_path.nil?
+    end
+
+    # Public: Extract type information for a method from its Sorbet signature.
+    #
+    # Tries multiple sources in order:
+    # 1. Runtime reflection (T::Utils.signature_for_method)
+    # 2. RBI files (if available)
+    #
+    # klass       - The Class containing the method
+    # method_name - The Symbol or String name of the method
+    #
+    # Returns a Hash with keys:
+    #   :typespec_type - Symbol or String representing the TypeSpec type
+    #   :nilable       - Boolean indicating if type is optional
+    #   :array         - Boolean indicating if type is an array
+    # Returns nil if no signature found
+    #
+    # Examples
+    #
+    #   class MySerializer
+    #     extend T::Sig
+    #
+    #     sig { returns(String) }
+    #     def name
+    #       "example"
+    #     end
+    #   end
+    #
+    #   extract_type_for(MySerializer, :name)
+    #   # => { typespec_type: :string, nilable: false, array: false }
+    #
+    def extract_type_for(klass, method_name)
+      # Try TypeDSL first (if available), then runtime reflection, then RBI files
+      extract_from_type_dsl(klass, method_name) ||
+        (available? ? extract_from_runtime(klass, method_name) : nil) ||
+        (rbi_available? ? extract_from_rbi(klass, method_name) : nil)
+    end
+
+    class << self
+    private
+
+      # Internal: Extract type from TypeDSL declaration.
+      def extract_from_type_dsl(klass, method_name)
+        return nil unless klass.respond_to?(:type_for_method)
+
+        type_annotation = klass.type_for_method(method_name)
+        return nil unless type_annotation
+
+        # Handle plain Ruby classes
+        if type_annotation.is_a?(Class)
+          type_name = type_annotation.name
+          mapped_type = config_type_mapping[type_name]
+          result = {
+            typespec_type: mapped_type || type_name,
+            nilable: false,
+            array: false,
+            type_class: type_annotation,
+          }
+          return result
+        end
+
+        # Handle Sorbet type annotations
+        sorbet_type_to_typespec(type_annotation)
+      rescue => e
+        warn "TypeSpec: Failed to extract type for #{klass}##{method_name}: #{e.class} - #{e.message}"
+        nil
+      end
+
+      # Internal: Get type mapping from config.
+      def config_type_mapping
+        TypeSpecFromSerializers.config.sorbet_to_typespec_type_mapping
+      end
+
+      # Internal: Extract type from runtime reflection.
+      def extract_from_runtime(klass, method_name)
+        method = klass.instance_method(method_name.to_sym)
+        extract_from_method(method)
+      rescue NameError
+        # Method doesn't exist on this class
+        nil
+      end
+
+      # Internal: Extract type from RBI files.
+      def extract_from_rbi(klass, method_name)
+        class_name = klass.name
+        return nil unless class_name
+
+        # Look up in unified RBI index
+        signature = rbi_unified_index["#{class_name}##{method_name}"]
+        return nil unless signature
+
+        # Parse the signature return type
+        parse_rbi_return_type(signature)
+      end
+
+      # Internal: Build a unified index from all RBI files.
+      #
+      # Returns Hash mapping "ClassName#method_name" => return_type_string
+      def rbi_unified_index
+        return @rbi_unified_index if defined?(@rbi_unified_index)
+
+        @rbi_unified_index = {}
+        return @rbi_unified_index unless rbi_path&.exist?
+
+        # Find RBI files, excluding gems/ (third-party gems won't have serializer methods)
+        # Only check annotations/ and dsl/ directories for performance
+        rbi_files = [
+          *Pathname.glob(rbi_path.join("annotations", "**", "*.rbi")),
+          *Pathname.glob(rbi_path.join("dsl", "**", "*.rbi")),
+        ]
+
+        # Parse each file and merge into unified index
+        rbi_files.each do |rbi_file|
+          tree = parse_rbi_file_cached(rbi_file)
+          next unless tree
+
+          # Extract all method signatures from this file
+          tree.index.each do |fqn, nodes|
+            next unless fqn.include?("#") # Only instance methods
+
+            nodes.each do |node|
+              return_type = node&.sigs&.first&.return_type
+              @rbi_unified_index[fqn] ||= return_type if return_type
+            end
+          end
+        rescue
+          # Ignore errors in individual files
+          next
+        end
+
+        @rbi_unified_index
+      end
+
+      # Internal: Parse an RBI file and cache the result.
+      #
+      # Returns parsed RBI tree or nil if parsing fails
+      def parse_rbi_file_cached(rbi_file)
+        @rbi_tree_cache ||= {}
+        @rbi_tree_cache[rbi_file.to_s] ||= ::RBI::Parser.parse_file(rbi_file)
+      rescue
+        # Cache the failure to avoid re-parsing
+        @rbi_tree_cache[rbi_file.to_s] = nil
+      end
+
+      # Internal: Parse a return type from RBI signature using RBI type system.
+      #
+      # type_string - String like "String", "T.nilable(Integer)", "T::Array[String]"
+      #
+      # Returns Hash with :typespec_type, :nilable, :array or nil
+      def parse_rbi_return_type(type_string)
+        type_string&.strip&.then { |s| ::RBI::Type.parse_string(s) }&.then { |t| rbi_type_to_typespec(t) }
+      rescue
+        # Parsing failed - return nil
+        nil
+      end
+
+      # Internal: Convert an RBI::Type to TypeSpec type information.
+      #
+      # rbi_type - RBI::Type object (Nilable, Generic, Simple, etc.)
+      #
+      # Returns Hash with :typespec_type, :nilable, :array or nil
+      def rbi_type_to_typespec(rbi_type)
+        result = {
+          typespec_type: nil,
+          nilable: false,
+          array: false,
+        }
+
+        # Unwrap T.nilable
+        if rbi_type.is_a?(::RBI::Type::Nilable)
+          result[:nilable] = true
+          rbi_type = rbi_type.type
+        end
+
+        # Unwrap T::Array
+        if rbi_type.is_a?(::RBI::Type::Generic) &&
+            rbi_type.name.in?(["::T::Array", "T::Array"])
+          result[:array] = true
+          rbi_type = rbi_type.params.first
+        end
+
+        # Extract the base type name
+        type_name = case rbi_type
+        when ::RBI::Type::Simple, ::RBI::Type::Generic
+          rbi_type.name
+        else
+          rbi_type.to_s
+        end
+
+        # Map to TypeSpec type (remove leading :: if present)
+        result[:typespec_type] = map_rbi_type(type_name.delete_prefix("::"))
+
+        result[:typespec_type] ? result : nil
+      end
+
+      # Internal: Map an RBI type string to TypeSpec type.
+      def map_rbi_type(type_string)
+        TypeSpecFromSerializers.config.sorbet_to_typespec_type_mapping[type_string] ||
+          ((type_string == "T::Boolean") ? :boolean : type_string)
+      end
+
+      # Internal: Extract type information from a Method object.
+      def extract_from_method(method)
+        sig = T::Utils.signature_for_method(method)
+        return nil unless sig&.return_type
+
+        sorbet_type_to_typespec(sig.return_type)
+      rescue
+        # Sorbet introspection failed, fall back to other inference methods
+        nil
+      end
+
+      # Internal: Convert a Sorbet type object to TypeSpec type information.
+      #
+      # sorbet_type - The Sorbet type object from the signature
+      #
+      # Returns Hash with :typespec_type, :nilable, :array, :type_class keys
+      # Returns nil if type cannot be mapped
+      def sorbet_type_to_typespec(sorbet_type)
+        base_result = {typespec_type: nil, nilable: false, array: false, type_class: nil}
+
+        # Unwrap T.nilable if present
+        if nilable?(sorbet_type)
+          base_result[:nilable] = true
+          sorbet_type = unwrap_nilable(sorbet_type)
+        end
+
+        # Dispatch to specific type handlers
+        handle_array_type(sorbet_type, base_result) ||
+          handle_hash_type(sorbet_type, base_result) ||
+          handle_set_type(sorbet_type, base_result) ||
+          handle_union_type(sorbet_type, base_result) ||
+          handle_untyped(sorbet_type, base_result) ||
+          handle_simple_type(sorbet_type, base_result)
+      end
+
+      # Internal: Handle T::Array types
+      def handle_array_type(sorbet_type, result)
+        return nil unless sorbet_type.is_a?(T::Types::TypedArray)
+
+        result[:array] = true
+        element_type = sorbet_type.type
+
+        # Shape types inside arrays: T::Array[{lon: Float, lat: Float}]
+        if shape_type = extract_shape_typespec(element_type)
+          return result.merge(typespec_type: shape_type)
+        end
+
+        # Nested complex types: T::Array[T::Array[X]], T::Array[T::Hash[K,V]]
+        if complex_element?(element_type)
+          nested = sorbet_type_to_typespec(element_type)
+          return nested&.then { |n|
+            typespec = n[:array] ? "#{n[:typespec_type]}[]" : n[:typespec_type]
+            result.merge(typespec_type: typespec)
+          }
+        end
+
+        # Simple array elements
+        handle_simple_type(element_type, result)
+      end
+
+      # Internal: Handle T::Hash types
+      def handle_hash_type(sorbet_type, result)
+        return nil unless sorbet_type.is_a?(T::Types::TypedHash)
+
+        value_type = map_sorbet_type(sorbet_type.values)
+        result.merge(typespec_type: "Record<#{value_type}>")
+      end
+
+      # Internal: Handle T::Set types (converted to arrays in TypeSpec)
+      def handle_set_type(sorbet_type, result)
+        return nil unless defined?(T::Types::TypedSet) && sorbet_type.is_a?(T::Types::TypedSet)
+
+        element_type = map_sorbet_type(sorbet_type.type)
+        result.merge(typespec_type: element_type, array: true)
+      end
+
+      # Internal: Handle T.any union types
+      def handle_union_type(sorbet_type, result)
+        return nil unless sorbet_type.is_a?(T::Types::Union) && !nilable?(sorbet_type)
+
+        non_nil_types = sorbet_type.types.reject { |t| t == T::Utils.coerce(NilClass) }
+
+        case non_nil_types.size
+        when 1
+          sorbet_type_to_typespec(non_nil_types.first)
+        else
+          mapped_types = non_nil_types.map { |t| map_sorbet_type(t) }.compact.uniq
+          typespec = mapped_types.size == 1 ? mapped_types.first : mapped_types.join(" | ")
+          result.merge(typespec_type: typespec)
+        end
+      end
+
+      # Internal: Handle T.untyped
+      def handle_untyped(sorbet_type, result)
+        return nil unless sorbet_type.is_a?(T::Types::Untyped)
+
+        result.merge(typespec_type: "unknown")
+      end
+
+      # Internal: Handle simple types (String, Integer, custom classes, etc.)
+      def handle_simple_type(sorbet_type, result)
+        result[:type_class] = extract_type_class(sorbet_type)
+        result[:typespec_type] = map_sorbet_type(sorbet_type)
+        result[:typespec_type] ? result : nil
+      end
+
+      # Internal: Extract shape type from FixedHash (e.g., {lon: Float, lat: Float})
+      def extract_shape_typespec(type)
+        return nil unless defined?(T::Types::FixedHash) && type.is_a?(T::Types::FixedHash)
+
+        # Access shape fields through multiple fallback paths
+        types_hash = [:@types, :@inner_types].find do |ivar|
+          type.instance_variable_get(ivar) rescue nil
+        end&.then { |ivar| type.instance_variable_get(ivar) } ||
+          (type.types if type.respond_to?(:types))
+
+        return nil unless types_hash
+
+        fields = types_hash.transform_values { |v| map_sorbet_type(v) }
+        "{#{fields.map { |k, v| "#{k}: #{v}" }.join(", ")}}"
+      end
+
+      # Internal: Check if type is a complex nested type
+      def complex_element?(type)
+        type.is_a?(T::Types::TypedArray) ||
+          type.is_a?(T::Types::TypedHash) ||
+          (defined?(T::Types::TypedSet) && type.is_a?(T::Types::TypedSet))
+      end
+
+      # Internal: Extract the Ruby class from a Sorbet type object.
+      #
+      # sorbet_type - The Sorbet type object
+      #
+      # Returns Class or nil
+      def extract_type_class(sorbet_type)
+        # Try multiple extraction strategies in order of preference
+        extract_from_pair_union(sorbet_type) ||
+          extract_from_typed_wrapper(sorbet_type) ||
+          extract_direct_class(sorbet_type)
+      rescue
+        # Type introspection failed - return nil
+      end
+
+      # Internal: Extract class from SimplePairUnion (e.g., T::Boolean)
+      def extract_from_pair_union(sorbet_type)
+        return nil unless sorbet_type.instance_of?(::T::Private::Types::SimplePairUnion)
+
+        [:@raw_a, :@raw_b]
+          .map { |ivar| sorbet_type.instance_variable_get(ivar) }
+          .reject { |type| type == NilClass }
+          .find { |type| type.is_a?(Class) }
+      end
+
+      # Internal: Extract class from typed wrappers (TypedArray, Simple, etc.)
+      def extract_from_typed_wrapper(sorbet_type)
+        [:type, :raw_type]
+          .lazy
+          .select { |method| sorbet_type.respond_to?(method) }
+          .map { |method| sorbet_type.public_send(method) }
+          .find { |value| value.is_a?(Class) }
+      end
+
+      # Internal: Extract class if sorbet_type itself is a Class
+      def extract_direct_class(sorbet_type)
+        sorbet_type if sorbet_type.is_a?(Class)
+      end
+
+      # Internal: Check if a Sorbet type is nilable (T.nilable wrapper).
+      def nilable?(sorbet_type)
+        # Handle SimplePairUnion (T.nilable in runtime)
+        if sorbet_type.instance_of?(::T::Private::Types::SimplePairUnion)
+          return sorbet_type.instance_variable_get(:@raw_b) == NilClass ||
+              sorbet_type.instance_variable_get(:@raw_a) == NilClass
+        end
+
+        # T.nilable wraps types in a T::Types::Union with NilClass
+        sorbet_type.is_a?(T::Types::Union) &&
+          sorbet_type.types.any? { |t| t == T::Utils.coerce(NilClass) }
+      end
+
+      # Internal: Unwrap T.nilable to get the underlying type.
+      def unwrap_nilable(sorbet_type)
+        return sorbet_type unless nilable?(sorbet_type)
+
+        # Handle SimplePairUnion
+        if sorbet_type.instance_of?(::T::Private::Types::SimplePairUnion)
+          raw_a, raw_b = sorbet_type.instance_variable_get(:@raw_a), sorbet_type.instance_variable_get(:@raw_b)
+          return (raw_a == NilClass) ? raw_b : raw_a
+        end
+
+        # Find the non-nil type in the union
+        sorbet_type.types.find { |t| t != T::Utils.coerce(NilClass) }
+      end
+
+      # Internal: Map a Sorbet type to a TypeSpec type.
+      #
+      # Returns Symbol for built-in types, String for custom types, or nil
+      def map_sorbet_type(sorbet_type)
+        type_class = extract_type_class(sorbet_type)
+        return nil unless type_class
+
+        type_name = type_class.name
+        return "unknown" unless type_name
+
+        config.sorbet_to_typespec_type_mapping[type_name] ||
+          (type_name == "T::Boolean" ? :boolean : type_name)
+      end
+
+      # Internal: Shorthand for config access
+      def config
+        TypeSpecFromSerializers.config
+      end
+    end
+  end
+end

data/lib/typespec_from_serializers/version.rb

@@ -2,5 +2,5 @@
 
 module TypeSpecFromSerializers
   # Public: This library adheres to semantic versioning.
-  VERSION = "0.1.1"
+  VERSION = "0.2.1"
 end

data/lib/typespec_from_serializers.rb

@@ -2,4 +2,6 @@
 
 require_relative "typespec_from_serializers/version"
 require_relative "typespec_from_serializers/dsl"
+require_relative "typespec_from_serializers/sorbet"
+require_relative "typespec_from_serializers/rbi"
 require_relative "typespec_from_serializers/railtie"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typespec_from_serializers
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Danila Poyarkov
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-01 00:00:00.000000000 Z
+date: 2025-12-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -59,6 +59,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: rbi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -241,6 +269,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: typespec_from_serializers helps you by automatically generating TypeSpec
   descriptions for your JSON serializers, allowing you typecheck your frontend code
   to ship fast and with confidence.
@@ -256,8 +298,15 @@ files:
 - README.md
 - lib/typespec_from_serializers.rb
 - lib/typespec_from_serializers/dsl.rb
+- lib/typespec_from_serializers/dsl/controller.rb
+- lib/typespec_from_serializers/dsl/serializer.rb
 - lib/typespec_from_serializers/generator.rb
+- lib/typespec_from_serializers/io.rb
+- lib/typespec_from_serializers/openapi_compiler.rb
 - lib/typespec_from_serializers/railtie.rb
+- lib/typespec_from_serializers/rbi.rb
+- lib/typespec_from_serializers/runner.rb
+- lib/typespec_from_serializers/sorbet.rb
 - lib/typespec_from_serializers/version.rb
 homepage: https://github.com/dannote/typespec_from_serializers
 licenses: