sorbet-baml 0.0.1 → 0.2.0

data/lib/sorbet_baml/comment_extractor.rb

@@ -0,0 +1,170 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SorbetBaml
+  # Extracts documentation comments from Sorbet struct and enum source files
+  class CommentExtractor
+    extend T::Sig
+
+    sig { params(klass: T.class_of(T::Struct)).returns(T::Hash[String, T.nilable(String)]) }
+    def self.extract_field_comments(klass)
+      # First try to get descriptions from the description extractor (extra field)
+      descriptions = DescriptionExtractor.extract_prop_descriptions(klass)
+      
+      # Then fall back to comment-based extraction for any missing descriptions
+      comments = {}
+      source_file = find_source_file(klass)
+      
+      if source_file && File.exist?(source_file)
+        lines = File.readlines(source_file)
+        extract_comments_from_lines(lines, T.must(T.must(klass.name).split('::').last), comments)
+      end
+      
+      # Merge with priority: description parameters > comments
+      descriptions.merge(comments) { |key, desc_param, comment| desc_param }
+    end
+
+    sig { params(klass: T.class_of(T::Enum)).returns(T::Hash[String, T.nilable(String)]) }
+    def self.extract_enum_comments(klass)
+      comments = {}
+      source_file = find_source_file(klass)
+      
+      return comments unless source_file && File.exist?(source_file)
+      
+      lines = File.readlines(source_file)
+      extract_enum_comments_from_lines(lines, T.must(T.must(klass.name).split('::').last), comments)
+      
+      comments
+    end
+
+    private
+
+    sig { params(klass: T::Class[T.anything]).returns(T.nilable(String)) }
+    def self.find_source_file(klass)
+      # Try to find where the class was defined
+      # This is a heuristic approach since Ruby doesn't provide reliable source location for classes
+      
+      # Method 1: Check if any methods have source location
+      begin
+        if klass.respond_to?(:new) && klass.method(:new).respond_to?(:source_location)
+          location = klass.method(:new).source_location
+          return location[0] if location
+        end
+      rescue
+        # Ignore errors
+      end
+      
+      # Method 2: Look at the current call stack for files that might contain the class
+      caller_locations.each do |location|
+        file_path = location.absolute_path || location.path
+        next unless file_path && File.exist?(file_path)
+        
+        # Read the file and check if it contains the class definition
+        begin
+          content = File.read(file_path)
+          class_name = T.must(klass.name).split('::').last
+          if content.match(/class\s+#{Regexp.escape(T.must(class_name))}\s*</)
+            return file_path
+          end
+        rescue
+          # Ignore file read errors
+        end
+      end
+      
+      nil
+    end
+
+    sig { params(lines: T::Array[String], class_name: String, comments: T::Hash[String, T.nilable(String)]).void }
+    def self.extract_comments_from_lines(lines, class_name, comments)
+      in_target_class = T.let(false, T::Boolean)
+      current_comment = T.let(nil, T.nilable(String))
+      brace_depth = 0
+      
+      lines.each do |line|
+        stripped = line.strip
+        
+        # Check if we're entering the target class
+        if stripped.match(/^class\s+#{Regexp.escape(class_name)}\s*<\s*T::Struct/)
+          in_target_class = true
+          brace_depth = 0
+          next
+        end
+        
+        next unless in_target_class
+        
+        # Track brace depth to handle nested classes
+        brace_depth += stripped.count('{')
+        brace_depth -= stripped.count('}')
+        
+        # Exit when we reach the end of the class
+        if stripped == 'end' && brace_depth == 0
+          break
+        end
+        
+        # Extract comment
+        if stripped.start_with?('#')
+          comment_text = T.must(stripped[1..-1]).strip
+          current_comment = current_comment ? "#{current_comment} #{comment_text}" : comment_text
+        elsif stripped.match(/^const\s+:(\w+)/) && current_comment
+          field_name = T.must(stripped.match(/^const\s+:(\w+)/))[1]
+          comments[T.must(field_name)] = current_comment
+          current_comment = nil
+        elsif !stripped.empty? && !stripped.start_with?('#')
+          # Reset comment if we hit non-comment, non-const line
+          current_comment = nil
+        end
+      end
+    end
+
+    sig { params(lines: T::Array[String], class_name: String, comments: T::Hash[String, T.nilable(String)]).void }
+    def self.extract_enum_comments_from_lines(lines, class_name, comments)
+      in_target_class = T.let(false, T::Boolean)
+      in_enums_block = T.let(false, T::Boolean)
+      current_comment = T.let(nil, T.nilable(String))
+      
+      lines.each do |line|
+        stripped = line.strip
+        
+        # Check if we're entering the target enum class
+        if stripped.match(/^class\s+#{Regexp.escape(class_name)}\s*<\s*T::Enum/)
+          in_target_class = true
+          next
+        end
+        
+        next unless in_target_class
+        
+        # Check if we're in the enums block
+        if stripped == 'enums do'
+          in_enums_block = true
+          next
+        end
+        
+        # Exit enums block
+        if in_enums_block && stripped == 'end'
+          in_enums_block = false
+          next
+        end
+        
+        # Exit class
+        if stripped == 'end' && !in_enums_block
+          break
+        end
+        
+        next unless in_enums_block
+        
+        # Extract comment
+        if stripped.start_with?('#')
+          comment_text = T.must(stripped[1..-1]).strip
+          current_comment = current_comment ? "#{current_comment} #{comment_text}" : comment_text
+        elsif stripped.match(/^(\w+)\s*=\s*new/) && current_comment
+          enum_name = T.must(stripped.match(/^(\w+)\s*=\s*new/))[1]
+          comments[T.must(enum_name)] = current_comment
+          current_comment = nil
+        elsif !stripped.empty? && !stripped.start_with?('#')
+          # Reset comment if we hit non-comment, non-enum line
+          current_comment = nil
+        end
+      end
+    end
+  end
+end

data/lib/sorbet_baml/converter.rb

@@ -2,6 +2,8 @@
 # frozen_string_literal: true
 
 require "sorbet-runtime"
+require "set"
+require_relative "comment_extractor"
 
 module SorbetBaml
   # Main converter class for transforming Sorbet types to BAML
@@ -16,31 +18,179 @@ module SorbetBaml
     sig { params(klasses: T::Array[T.class_of(T::Struct)], options: T::Hash[Symbol, T.untyped]).returns(String) }
     def self.from_structs(klasses, options = {})
       converter = new(options)
-      klasses.map { |klass| converter.convert_struct(klass) }.join("\n\n")
+      
+      if converter.instance_variable_get(:@include_dependencies)
+        # When dependencies are enabled, collect all unique dependencies and convert once
+        all_dependencies = Set.new
+        enum_dependencies = Set.new
+        
+        klasses.each do |klass|
+          deps = DependencyResolver.resolve_dependencies(klass)
+          all_dependencies.merge(deps)
+          enum_deps = converter.send(:find_enum_dependencies, deps)
+          enum_dependencies.merge(enum_deps)
+        end
+        
+        # Convert all unique types
+        converted_types = []
+        enum_dependencies.each { |enum_klass| converted_types << converter.convert_enum(enum_klass) }
+        all_dependencies.each { |struct_klass| converted_types << converter.send(:convert_single_struct, struct_klass) }
+        
+        converted_types.join("\n\n")
+      else
+        # When dependencies are disabled, convert each struct individually
+        klasses.map { |klass| converter.send(:convert_single_struct, klass) }.join("\n\n")
+      end
+    end
+
+    sig { params(klass: T.class_of(T::Enum), options: T::Hash[Symbol, T.untyped]).returns(String) }
+    def self.from_enum(klass, options = {})
+      new(options).convert_enum(klass)
     end
 
     sig { params(options: T::Hash[Symbol, T.untyped]).void }
     def initialize(options = {})
       @options = options
       @indent_size = T.let(options.fetch(:indent_size, 2), Integer)
-      @include_descriptions = T.let(options.fetch(:include_descriptions, false), T::Boolean)
+      @include_descriptions = T.let(options.fetch(:include_descriptions, true), T::Boolean)
+      @include_dependencies = T.let(options.fetch(:include_dependencies, true), T::Boolean)
     end
 
     sig { params(klass: T.class_of(T::Struct)).returns(String) }
     def convert_struct(klass)
+      if @include_dependencies
+        # Get all dependencies in correct order and convert them all
+        dependencies = DependencyResolver.resolve_dependencies(klass)
+        
+        # Also find all enum dependencies
+        enum_dependencies = find_enum_dependencies(dependencies)
+        
+        # Convert enums first, then structs
+        converted_types = []
+        enum_dependencies.each { |enum_klass| converted_types << convert_enum(enum_klass) }
+        dependencies.each { |dep_klass| converted_types << convert_single_struct(dep_klass) }
+        
+        converted_types.join("\n\n")
+      else
+        # Just convert the single struct
+        convert_single_struct(klass)
+      end
+    end
+
+    sig { params(klass: T.class_of(T::Enum)).returns(String) }
+    def convert_enum(klass)
+      class_name = klass.name || klass.to_s
+      simple_name = class_name.split('::').last
+      lines = ["enum #{simple_name} {"]
+      
+      # Extract comments if requested
+      comments = @include_descriptions ? CommentExtractor.extract_enum_comments(klass) : {}
+      
+      # Get all enum values by calling values method
+      enum_values = klass.values
+      enum_values.each do |enum_instance|
+        value = enum_instance.serialize
+        
+        # Find the constant name for this value
+        constant_name = T.let(nil, T.nilable(String))
+        klass.constants.each do |const_name|
+          const_value = klass.const_get(const_name)
+          if const_value.is_a?(klass) && const_value.serialize == value
+            constant_name = const_name.to_s
+            break
+          end
+        end
+        
+        line = "#{' ' * @indent_size}\"#{value}\""
+        
+        # Add description if available (BAML uses @description annotations, not comments)
+        if @include_descriptions && constant_name && comments[constant_name]
+          line += " @description(\"#{T.must(comments[constant_name]).gsub('"', '\\"')}\")"
+        end
+        
+        lines << line
+      end
+      
+      lines << "}"
+      lines.join("\n")
+    end
+
+    private
+
+    sig { params(klass: T.class_of(T::Struct)).returns(String) }
+    def convert_single_struct(klass)
       props = klass.props
       
       class_name = klass.name || klass.to_s
       simple_name = class_name.split('::').last
       lines = ["class #{simple_name} {"]
       
+      # Extract comments if requested
+      comments = @include_descriptions ? CommentExtractor.extract_field_comments(klass) : {}
+      
       props.each do |name, prop_info|
         baml_type = TypeMapper.map_type(prop_info[:type_object])
-        lines << "#{' ' * @indent_size}#{name} #{baml_type}"
+        line = "#{' ' * @indent_size}#{name} #{baml_type}"
+        
+        # Add description if available (BAML uses @description annotations)
+        if @include_descriptions && comments[name.to_s]
+          escaped_comment = T.must(comments[name.to_s]).gsub('"', '\\"')
+          line += " @description(\"#{escaped_comment}\")"
+        end
+        
+        lines << line
       end
       
       lines << "}"
       lines.join("\n")
     end
+    
+    sig { params(struct_classes: T::Array[T.class_of(T::Struct)]).returns(T::Array[T.class_of(T::Enum)]) }
+    def find_enum_dependencies(struct_classes)
+      enum_deps = Set.new
+      
+      struct_classes.each do |struct_klass|
+        struct_klass.props.each do |_name, prop_info|
+          type_object = prop_info[:type_object]
+          enum_deps.merge(extract_enum_types(type_object))
+        end
+      end
+      
+      enum_deps.to_a
+    end
+    
+    sig { params(type_object: T.untyped).returns(T::Array[T.class_of(T::Enum)]) }
+    def extract_enum_types(type_object)
+      return [] if type_object.nil?
+      
+      case type_object
+      when T::Types::Simple
+        extract_enum_from_simple_type(type_object.raw_type)
+      when T::Types::TypedArray
+        extract_enum_types(type_object.type)
+      when T::Types::TypedHash
+        # Check both key and value types
+        key_types = extract_enum_types(type_object.keys)
+        value_types = extract_enum_types(type_object.values)
+        key_types + value_types
+      else
+        # Check if it's a union type
+        if type_object.respond_to?(:types)
+          type_object.types.flat_map { |t| extract_enum_types(t) }
+        else
+          []
+        end
+      end
+    end
+    
+    sig { params(raw_type: T.untyped).returns(T::Array[T.class_of(T::Enum)]) }
+    def extract_enum_from_simple_type(raw_type)
+      # Check if this raw_type is a T::Enum subclass
+      if raw_type.is_a?(Class) && raw_type < T::Enum
+        [raw_type]
+      else
+        []
+      end
+    end
   end
 end

data/lib/sorbet_baml/dependency_resolver.rb

@@ -0,0 +1,99 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module SorbetBaml
+  # Resolves dependencies between T::Struct types and orders them topologically
+  class DependencyResolver
+    extend T::Sig
+
+    sig { params(klass: T.class_of(T::Struct)).returns(T::Array[T.class_of(T::Struct)]) }
+    def self.resolve_dependencies(klass)
+      new.resolve_dependencies(klass)
+    end
+
+    sig { void }
+    def initialize
+      @visited = T.let(Set.new, T::Set[T.class_of(T::Struct)])
+      @dependencies = T.let([], T::Array[T.class_of(T::Struct)])
+    end
+
+    sig { params(klass: T.class_of(T::Struct)).returns(T::Array[T.class_of(T::Struct)]) }
+    def resolve_dependencies(klass)
+      @visited.clear
+      @dependencies.clear
+      
+      # Perform depth-first search to find all dependencies
+      visit(klass)
+      
+      # Dependencies are already in correct topological order
+      # (dependencies first, then the types that depend on them)
+      @dependencies
+    end
+
+    private
+
+    sig { params(klass: T.class_of(T::Struct)).void }
+    def visit(klass)
+      return if @visited.include?(klass)
+      
+      @visited.add(klass)
+      
+      # Find all T::Struct dependencies in this class
+      struct_dependencies = find_struct_dependencies(klass)
+      
+      # Visit dependencies first (depth-first)
+      struct_dependencies.each { |dep| visit(dep) }
+      
+      # Add this class after its dependencies
+      @dependencies << klass
+    end
+
+    sig { params(klass: T.class_of(T::Struct)).returns(T::Array[T.class_of(T::Struct)]) }
+    def find_struct_dependencies(klass)
+      dependencies = []
+      
+      klass.props.each do |_name, prop_info|
+        type_object = prop_info[:type_object]
+        dependencies.concat(extract_struct_types(type_object))
+      end
+      
+      dependencies.uniq
+    end
+
+    sig { params(type_object: T.untyped).returns(T::Array[T.class_of(T::Struct)]) }
+    def extract_struct_types(type_object)
+      return [] if type_object.nil?
+      
+      case type_object
+      when T::Types::Simple
+        extract_from_simple_type(type_object.raw_type)
+      when T::Types::TypedArray
+        extract_struct_types(type_object.type)
+      when T::Types::TypedHash
+        # Check both key and value types
+        key_types = extract_struct_types(type_object.keys)
+        value_types = extract_struct_types(type_object.values)
+        key_types + value_types
+      else
+        # Check if it's a union type
+        if type_object.respond_to?(:types)
+          type_object.types.flat_map { |t| extract_struct_types(t) }
+        else
+          []
+        end
+      end
+    end
+
+    sig { params(raw_type: T.untyped).returns(T::Array[T.class_of(T::Struct)]) }
+    def extract_from_simple_type(raw_type)
+      # Check if this raw_type is a T::Struct subclass
+      if raw_type.is_a?(Class) && raw_type < T::Struct
+        [raw_type]
+      else
+        []
+      end
+    end
+  end
+end

data/lib/sorbet_baml/description_extension.rb

@@ -0,0 +1,34 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module SorbetBaml
+  # Extension module to add description: parameter support to T::Struct
+  module DescriptionExtension
+    extend T::Sig
+    
+    # Override const to support description parameter
+    sig { params(name: Symbol, type: T.untyped, description: T.nilable(String), kwargs: T.untyped).void }
+    def const(name, type, description: nil, **kwargs)
+      if description
+        super(name, type, extra: { description: description }, **kwargs)
+      else
+        super(name, type, **kwargs)
+      end
+    end
+    
+    # Override prop to support description parameter  
+    sig { params(name: Symbol, type: T.untyped, description: T.nilable(String), kwargs: T.untyped).void }
+    def prop(name, type, description: nil, **kwargs)
+      if description
+        super(name, type, extra: { description: description }, **kwargs)
+      else
+        super(name, type, **kwargs)
+      end
+    end
+  end
+end
+
+# Automatically extend T::Struct with description support
+T::Struct.extend(SorbetBaml::DescriptionExtension)

data/lib/sorbet_baml/description_extractor.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module SorbetBaml
+  # Extracts description parameters from T::Struct prop and const declarations
+  class DescriptionExtractor
+    extend T::Sig
+
+    sig { params(klass: T::Class[T.anything]).returns(T::Hash[String, T.nilable(String)]) }
+    def self.extract_prop_descriptions(klass)
+      descriptions = {}
+      
+      # Check if this is a T::Struct with props
+      return descriptions unless klass.respond_to?(:props)
+      
+      begin
+        T.unsafe(klass).props.each do |field_name, prop_info|
+          next unless prop_info.is_a?(Hash)
+          
+          # Check if the prop has a description in the :extra field
+          extra = prop_info[:extra]
+          if extra.is_a?(Hash) && extra[:description].is_a?(String)
+            descriptions[field_name.to_s] = extra[:description]
+          end
+        end
+      rescue => e
+        # Handle any errors gracefully and return empty hash
+        return {}
+      end
+      
+      descriptions
+    end
+  end
+end

data/lib/sorbet_baml/enum_extensions.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module SorbetBaml
+  # Extensions to add BAML conversion methods to T::Enum
+  module EnumExtensions
+    extend T::Sig
+
+    # Convert this enum to BAML type definition
+    sig { params(options: T::Hash[Symbol, T.untyped]).returns(String) }
+    def to_baml(options = {})
+      baml_type_definition(options)
+    end
+
+    # Convert this enum to BAML type definition with options
+    sig { params(options: T::Hash[Symbol, T.untyped]).returns(String) }
+    def baml_type_definition(options = {})
+      SorbetBaml::Converter.from_enum(T.cast(self, T.class_of(T::Enum)), options)
+    end
+  end
+end

data/lib/sorbet_baml/struct_extensions.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module SorbetBaml
+  # Extensions to add BAML conversion methods to T::Struct
+  module StructExtensions
+    extend T::Sig
+
+    # Convert this struct to BAML type definition
+    sig { params(options: T::Hash[Symbol, T.untyped]).returns(String) }
+    def to_baml(options = {})
+      baml_type_definition(options)
+    end
+
+    # Convert this struct to BAML type definition with options
+    sig { params(options: T::Hash[Symbol, T.untyped]).returns(String) }
+    def baml_type_definition(options = {})
+      SorbetBaml::Converter.from_struct(T.cast(self, T.class_of(T::Struct)), options)
+    end
+  end
+end

data/lib/sorbet_baml/type_mapper.rb

@@ -17,10 +17,12 @@ module SorbetBaml
         map_simple_type(type_object.raw_type)
       when T::Types::TypedArray
         map_array_type(type_object)
+      when T::Types::TypedHash
+        map_hash_type(type_object)
       else
-        # Check if it's a union type (T.nilable)
+        # Check if it's a union type (T.nilable or T.any)
         if type_object.respond_to?(:types)
-          map_nilable_type(type_object)
+          map_union_type(type_object)
         else
           # Fallback for unknown types
           "unknown"
@@ -46,8 +48,8 @@ module SorbetBaml
       when "Date", "DateTime", "Time"
         "string"
       else
-        # Check if it's a T::Struct
-        if raw_type < T::Struct
+        # Check if it's a T::Struct or T::Enum
+        if raw_type < T::Struct || raw_type < T::Enum
           type_name = raw_type.name || raw_type.to_s
           type_name.split('::').last || "unknown"
         else
@@ -57,23 +59,58 @@ module SorbetBaml
     end
 
     sig { params(type_object: T.untyped).returns(String) }
-    def self.map_nilable_type(type_object)
-      # Extract the non-nil type from the union
+    def self.map_union_type(type_object)
       types = type_object.types
-      non_nil_type = types.find { |t| t.raw_type != NilClass }
+      nil_type = types.find { |t| t.raw_type == NilClass }
+      non_nil_types = types.reject { |t| t.raw_type == NilClass }
       
-      if non_nil_type
-        base_type = map_type(non_nil_type)
-        "#{base_type}?"
+      if non_nil_types.empty?
+        return "null"
+      end
+      
+      if non_nil_types.size == 1
+        # This is T.nilable(T) - single type with nil
+        base_type = map_type(non_nil_types.first)
+        return nil_type ? "#{base_type}?" : base_type
+      end
+      
+      # This is T.any with multiple types
+      mapped_types = non_nil_types.map { |t| map_type(t) }
+      
+      # Special case: TrueClass + FalseClass = bool
+      if mapped_types.sort == ["bool", "bool"]
+        union_string = "bool"
       else
-        "null"
+        # Remove duplicates and join
+        union_string = mapped_types.uniq.join(" | ")
+      end
+      
+      # If nil is present, wrap in parentheses and add ?
+      if nil_type
+        "(#{union_string})?"
+      else
+        union_string
       end
     end
 
     sig { params(type_object: T.untyped).returns(String) }
     def self.map_array_type(type_object)
       element_type = map_type(type_object.type)
-      "#{element_type}[]"
+      
+      # If element type contains union (|), wrap in parentheses for correct precedence
+      if element_type.include?("|")
+        "(#{element_type})[]"
+      else
+        "#{element_type}[]"
+      end
+    end
+
+    sig { params(type_object: T.untyped).returns(String) }
+    def self.map_hash_type(type_object)
+      # T::Types::TypedHash has keys and values methods
+      key_type = map_type(type_object.keys)
+      value_type = map_type(type_object.values)
+      "map<#{key_type}, #{value_type}>"
     end
   end
 end

data/lib/sorbet_baml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SorbetBaml
-  VERSION = "0.0.1"
+  VERSION = "0.2.0"
 end