sorbet-baml 0.0.1 → 0.1.0

data/docs/troubleshooting.md

@@ -18,6 +18,16 @@ end
 class User < T::Struct
   const :name, String
 end
+
+# Generate BAML
+User.to_baml
+```
+
+**Generated BAML:**
+```baml
+class User {
+  name string
+}
 ```
 
 ### Empty output
@@ -29,14 +39,44 @@ end
 ```ruby
 class User < T::Struct
   const :name, String  # Add properties
+  const :age, Integer
 end
+
+User.to_baml
+```
+
+**Generated BAML:**
+```baml
+class User {
+  name string
+  age int
+}
 ```
 
-### Circular dependency detected
+### Self-referential types work fine
+
+**Problem**: You think self-referential types aren't supported.
+
+**Solution**: They actually work perfectly! Self-referential types are fully supported:
+
+```ruby
+class Category < T::Struct
+  const :name, String
+  const :parent, T.nilable(Category)
+  const :children, T::Array[Category]
+end
 
-**Problem**: Two structs reference each other creating an infinite loop.
+Category.to_baml
+```
 
-**Solution**: This is not yet supported. Consider flattening the structure or using a different approach.
+**Generated BAML:**
+```baml
+class Category {
+  name string
+  parent Category?
+  children Category[]
+}
+```
 
 ## Type-Specific Issues
 
@@ -46,10 +86,23 @@ Ensure you're using the Sorbet array syntax:
 
 ```ruby
 # ❌ Wrong
-const :items, Array
+class User < T::Struct
+  const :items, Array  # Generic Array won't work
+end
 
 # ✅ Correct
-const :items, T::Array[String]
+class User < T::Struct
+  const :items, T::Array[String]
+end
+
+User.to_baml
+```
+
+**Generated BAML:**
+```baml
+class User {
+  items string[]
+}
 ```
 
 ### Optional fields showing as required
@@ -58,24 +111,181 @@ Make sure to use `T.nilable`:
 
 ```ruby
 # ❌ Wrong - will be required
-const :email, String
+class User < T::Struct
+  const :email, String
+end
 
 # ✅ Correct - will be optional
-const :email, T.nilable(String)
+class User < T::Struct
+  const :email, T.nilable(String)
+end
+
+User.to_baml
+```
+
+**Generated BAML:**
+```baml
+class User {
+  email string?
+}
+```
+
+### Union types not working
+
+Ensure you're using `T.any` for union types:
+
+```ruby
+# ❌ Wrong
+class Config < T::Struct
+  const :value, String || Integer  # Ruby OR, not Sorbet union
+end
+
+# ✅ Correct
+class Config < T::Struct
+  const :value, T.any(String, Integer)
+end
+
+Config.to_baml
+```
+
+**Generated BAML:**
+```baml
+class Config {
+  value string | int
+}
+```
+
+### Hash types not mapping correctly
+
+Use the full `T::Hash[K, V]` syntax:
+
+```ruby
+# ❌ Wrong
+class User < T::Struct
+  const :metadata, Hash  # Generic Hash won't work
+end
+
+# ✅ Correct
+class User < T::Struct
+  const :metadata, T::Hash[String, T.any(String, Integer)]
+end
+
+User.to_baml
+```
+
+**Generated BAML:**
+```baml
+class User {
+  metadata map<string, string | int>
+}
+```
+
+## Dependency Issues
+
+### Missing dependencies in output
+
+Use `include_dependencies: true` to automatically include all referenced types:
+
+```ruby
+class Address < T::Struct
+  const :street, String
+  const :city, String
+end
+
+class User < T::Struct
+  const :name, String
+  const :address, Address
+end
+
+# ❌ Only outputs User class
+User.to_baml
+
+# ✅ Outputs both Address and User in correct order
+User.to_baml(include_dependencies: true)
+```
+
+**Generated BAML (with dependencies):**
+```baml
+class Address {
+  street string
+  city string
+}
+
+class User {
+  name string
+  address Address
+}
+```
+
+### Wrong dependency order
+
+The gem automatically handles dependency ordering using topological sorting. Dependencies always come before the types that reference them.
+
+## Enum Issues
+
+### Enums not converting
+
+Ensure you're using the correct T::Enum syntax:
+
+```ruby
+# ❌ Wrong
+class Status
+  ACTIVE = 'active'
+  INACTIVE = 'inactive'
+end
+
+# ✅ Correct
+class Status < T::Enum
+  enums do
+    Active = new('active')
+    Inactive = new('inactive')
+  end
+end
+
+Status.to_baml
+```
+
+**Generated BAML:**
+```baml
+enum Status {
+  "active"
+  "inactive"
+}
 ```
 
 ## Getting Help
 
-1. Check the [Type Mapping Reference](./type-mapping.md)
-2. Review the examples in [Getting Started](./getting-started.md)
+1. Check the [Type Mapping Reference](./type-mapping.md) for complete type support
+2. Review examples in [Getting Started](./getting-started.md) and [Advanced Usage](./advanced-usage.md)
 3. File an issue at https://github.com/vicentereig/sorbet-baml/issues
 
-## Debug Mode
+## Advanced Debugging
 
-To see detailed conversion information:
+### Inspect Sorbet type information
 
 ```ruby
-# Future feature - not yet implemented
-SorbetBaml.debug = true
-baml = SorbetBaml.from_struct(MyStruct)
+# See what Sorbet sees for your struct
+MyStruct.props
+# => {name: String, age: Integer, ...}
+
+# Check if a class is a T::Struct
+MyStruct < T::Struct
+# => true
+
+# See enum values
+MyEnum.values
+# => [#<MyEnum:0x... @serialize="value1">, ...]
+```
+
+### Testing your BAML output
+
+```ruby
+# Verify the output looks correct
+baml = User.to_baml(include_dependencies: true)
+puts baml
+
+# Check that all expected types are included
+expected_types = ['class User', 'class Address', 'enum Status']
+expected_types.all? { |type| baml.include?(type) }
+# => true
 ```

data/docs/type-mapping.md

@@ -1,6 +1,6 @@
 # Type Mapping Reference
 
-Complete mapping between Sorbet types and BAML output.
+Complete mapping between Sorbet types and BAML output. All listed types are **fully supported**.
 
 ## Basic Types
 
@@ -12,54 +12,181 @@ Complete mapping between Sorbet types and BAML output.
 | `T::Boolean` | `bool` | `active bool` |
 | `NilClass` | `null` | `null` |
 | `Symbol` | `string` | `status string` |
+| `Date/DateTime/Time` | `string` | `created_at string` |
 
-## Optional Types
+## Optional Types (T.nilable)
 
 | Sorbet Type | BAML Output | Example |
 |-------------|-------------|---------|
 | `T.nilable(String)` | `string?` | `email string?` |
 | `T.nilable(Integer)` | `int?` | `age int?` |
+| `T.nilable(MyStruct)` | `MyStruct?` | `address Address?` |
 
 ## Collection Types
 
 | Sorbet Type | BAML Output | Example |
 |-------------|-------------|---------|
 | `T::Array[String]` | `string[]` | `tags string[]` |
-| `T::Array[T::Struct]` | `StructName[]` | `addresses Address[]` |
+| `T::Array[Integer]` | `int[]` | `scores int[]` |
+| `T::Array[MyStruct]` | `MyStruct[]` | `addresses Address[]` |
 
-## Nested Structures
+## Hash/Map Types
+
+| Sorbet Type | BAML Output | Example |
+|-------------|-------------|---------|
+| `T::Hash[String, String]` | `map<string, string>` | `metadata map<string, string>` |
+| `T::Hash[String, Integer]` | `map<string, int>` | `counts map<string, int>` |
+| `T::Hash[Symbol, String]` | `map<string, string>` | `config map<string, string>` |
+
+## Union Types (T.any)
+
+| Sorbet Type | BAML Output | Example |
+|-------------|-------------|---------|
+| `T.any(String, Integer)` | `string \| int` | `value string \| int` |
+| `T.any(String, Integer, Float)` | `string \| int \| float` | `mixed string \| int \| float` |
+| `T.nilable(T.any(String, Integer))` | `(string \| int)?` | `optional (string \| int)?` |
+
+## Complex Collection Types
+
+| Sorbet Type | BAML Output | Example |
+|-------------|-------------|---------|
+| `T::Array[T.any(String, Integer)]` | `(string \| int)[]` | `mixed_array (string \| int)[]` |
+| `T::Hash[String, T.any(String, Integer)]` | `map<string, string \| int>` | `settings map<string, string \| int>` |
+| `T::Hash[String, T::Array[String]]` | `map<string, string[]>` | `labels map<string, string[]>` |
+
+## Structured Types
+
+### T::Struct to BAML Classes
 
 ```ruby
-# Input
 class Address < T::Struct
   const :street, String
   const :city, String
+  const :postal_code, T.nilable(String)
 end
 
 class User < T::Struct
   const :name, String
+  const :age, Integer
   const :address, Address
+  const :tags, T::Array[String]
 end
+```
 
-# Output
-class Address {
-  street string
-  city string
-}
+```ruby
+User.to_baml
+```
 
+**Generated BAML:**
+```baml
 class User {
   name string
+  age int
   address Address
+  tags string[]
+}
+```
+
+### T::Enum to BAML Enums
+
+```ruby
+class Status < T::Enum
+  enums do
+    Active = new('active')
+    Inactive = new('inactive')
+    Pending = new('pending')
+  end
+end
+
+class User < T::Struct
+  const :name, String
+  const :status, Status
+end
+```
+
+```ruby
+[Status, User].map(&:to_baml).join("\n\n")
+```
+
+**Generated BAML:**
+```baml
+enum Status {
+  "active"
+  "inactive"
+  "pending"
+}
+
+class User {
+  name string
+  status Status
+}
+```
+
+### Complex Real-World Example
+
+```ruby
+class Priority < T::Enum
+  enums do
+    Low = new('low')
+    Medium = new('medium')
+    High = new('high')
+  end
+end
+
+class Task < T::Struct
+  const :title, String
+  const :description, T.nilable(String)
+  const :priority, Priority
+  const :tags, T::Array[String]
+  const :metadata, T::Hash[String, T.any(String, Integer)]
+  const :subtasks, T::Array[Task]
+end
+```
+
+```ruby
+[Priority, Task].map(&:to_baml).join("\n\n")
+```
+
+**Generated BAML:**
+```baml
+enum Priority {
+  "low"
+  "medium"
+  "high"
 }
+
+class Task {
+  title string
+  description string?
+  priority Priority
+  tags string[]
+  metadata map<string, string | int>
+  subtasks Task[]
+}
+```
+
+## Advanced Features
+
+### Dependency Management
+
+```ruby
+# Dependencies automatically included with smart defaults
+User.to_baml
+# Outputs Address, then User in correct order
+```
+
+### Custom Formatting
+
+```ruby
+# Smart defaults include dependencies automatically
+User.to_baml(indent_size: 4)
 ```
 
-## Not Yet Supported
+## Future Enhancements (Optional)
 
-These types will be added in future versions:
+These are nice-to-have features for future versions:
 
-- `T::Hash[K, V]` → `map<K, V>`
-- `T.any(Type1, Type2)` → `Type1 | Type2`
-- `T::Enum` subclasses → `enum Name { ... }`
 - `T.type_alias` → `type Name = ...`
-- `T::Set[T]` → `T[]` (with uniqueness note)
-- `T::Range[T]` → Will need special handling
+- Field descriptions from comments
+- Custom naming strategies (snake_case ↔ camelCase)
+- Self-referential type handling

data/lib/sorbet_baml/comment_extractor.rb

@@ -0,0 +1,165 @@
+# 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)
+      comments = {}
+      source_file = find_source_file(klass)
+      
+      return comments unless source_file && File.exist?(source_file)
+      
+      lines = File.readlines(source_file)
+      extract_comments_from_lines(lines, klass.name.split('::').last, comments)
+      
+      comments
+    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, klass.name.split('::').last, comments)
+      
+      comments
+    end
+
+    private
+
+    sig { params(klass: Class).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 = klass.name.split('::').last
+          if content.match(/class\s+#{Regexp.escape(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 = false
+      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 = stripped[1..-1].strip
+          current_comment = current_comment ? "#{current_comment} #{comment_text}" : comment_text
+        elsif stripped.match(/^const\s+:(\w+)/) && current_comment
+          field_name = stripped.match(/^const\s+:(\w+)/)[1]
+          comments[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 = false
+      in_enums_block = false
+      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 = 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 = stripped.match(/^(\w+)\s*=\s*new/)[1]
+          comments[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