sorbet-baml 0.1.0 → 0.2.0

data/lib/sorbet_baml/comment_extractor.rb

@@ -8,15 +8,20 @@ module SorbetBaml
 
     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)
       
-      return comments unless source_file && File.exist?(source_file)
-      
-      lines = File.readlines(source_file)
-      extract_comments_from_lines(lines, klass.name.split('::').last, comments)
+      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
       
-      comments
+      # 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)]) }
@@ -27,14 +32,14 @@ module SorbetBaml
       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)
+      extract_enum_comments_from_lines(lines, T.must(T.must(klass.name).split('::').last), comments)
       
       comments
     end
 
     private
 
-    sig { params(klass: Class).returns(T.nilable(String)) }
+    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
@@ -57,8 +62,8 @@ module SorbetBaml
         # 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*</)
+          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
@@ -71,7 +76,7 @@ module SorbetBaml
 
     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
+      in_target_class = T.let(false, T::Boolean)
       current_comment = T.let(nil, T.nilable(String))
       brace_depth = 0
       
@@ -98,11 +103,11 @@ module SorbetBaml
         
         # Extract comment
         if stripped.start_with?('#')
-          comment_text = stripped[1..-1].strip
+          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 = stripped.match(/^const\s+:(\w+)/)[1]
-          comments[field_name] = 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
@@ -113,8 +118,8 @@ module SorbetBaml
 
     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
+      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|
@@ -149,11 +154,11 @@ module SorbetBaml
         
         # Extract comment
         if stripped.start_with?('#')
-          comment_text = stripped[1..-1].strip
+          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 = stripped.match(/^(\w+)\s*=\s*new/)[1]
-          comments[enum_name] = 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

data/lib/sorbet_baml/converter.rb

@@ -92,7 +92,7 @@ module SorbetBaml
         value = enum_instance.serialize
         
         # Find the constant name for this value
-        constant_name = nil
+        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
@@ -105,7 +105,7 @@ module SorbetBaml
         
         # Add description if available (BAML uses @description annotations, not comments)
         if @include_descriptions && constant_name && comments[constant_name]
-          line += " @description(\"#{comments[constant_name].gsub('"', '\\"')}\")"
+          line += " @description(\"#{T.must(comments[constant_name]).gsub('"', '\\"')}\")"
         end
         
         lines << line
@@ -134,7 +134,7 @@ module SorbetBaml
         
         # Add description if available (BAML uses @description annotations)
         if @include_descriptions && comments[name.to_s]
-          escaped_comment = comments[name.to_s].gsub('"', '\\"')
+          escaped_comment = T.must(comments[name.to_s]).gsub('"', '\\"')
           line += " @description(\"#{escaped_comment}\")"
         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/version.rb

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

data/lib/sorbet_baml.rb

@@ -6,6 +6,9 @@ require_relative "sorbet_baml/version"
 require_relative "sorbet_baml/converter"
 require_relative "sorbet_baml/type_mapper"
 require_relative "sorbet_baml/dependency_resolver"
+require_relative "sorbet_baml/comment_extractor"
+require_relative "sorbet_baml/description_extractor"
+require_relative "sorbet_baml/description_extension"
 require_relative "sorbet_baml/struct_extensions"
 require_relative "sorbet_baml/enum_extensions"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sorbet-baml
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Vicente Reig Rincon de Arellano
@@ -36,18 +36,17 @@ files:
 - ".idea/inspectionProfiles/Project_Default.xml"
 - ".rspec"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- docs/README.md
-- docs/advanced-usage.md
-- docs/getting-started.md
-- docs/troubleshooting.md
-- docs/type-mapping.md
+- examples/description_parameters.rb
 - lib/sorbet_baml.rb
 - lib/sorbet_baml/comment_extractor.rb
 - lib/sorbet_baml/converter.rb
 - lib/sorbet_baml/dependency_resolver.rb
+- lib/sorbet_baml/description_extension.rb
+- lib/sorbet_baml/description_extractor.rb
 - lib/sorbet_baml/enum_extensions.rb
 - lib/sorbet_baml/struct_extensions.rb
 - lib/sorbet_baml/type_mapper.rb

data/docs/README.md

@@ -1,117 +0,0 @@
-# sorbet-baml Documentation
-
-Developer documentation for the sorbet-baml gem.
-
-## For Users
-
-If you want to use this gem in your project:
-
-1. **[Getting Started](./getting-started.md)** - Installation and basic usage
-2. **[Type Mapping Reference](./type-mapping.md)** - Complete type conversion table
-3. **[Advanced Usage](./advanced-usage.md)** - Complex scenarios and integrations
-4. **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
-
-## For Contributors
-
-This gem has reached **feature completeness** for core BAML conversion needs. The implementation is production-ready with:
-
-- ✅ **Complete type support** - All Sorbet types mapped to BAML
-- ✅ **Ruby-idiomatic API** - `.to_baml` method on all T::Struct/T::Enum classes  
-- ✅ **Dependency management** - Automatic topological sorting
-- ✅ **100% test coverage** - 34 comprehensive test cases
-- ✅ **Full Sorbet type safety** - Zero type errors
-
-Future enhancements are optional nice-to-haves rather than core requirements.
-
-## Quick Example
-
-```ruby
-# Define a Sorbet struct
-class User < T::Struct
-  const :name, String
-  const :age, Integer
-  const :email, T.nilable(String)
-end
-
-# Convert to BAML (Ruby-idiomatic API)
-require 'sorbet-baml'
-User.to_baml
-
-# Legacy API also supported
-# SorbetBaml.from_struct(User)
-```
-
-**Generated BAML:**
-```baml
-class User {
-  name string
-  age int
-  email string?
-}
-```
-
-## Design Goals
-
-1. **Ruby-Idiomatic** - Natural `.to_baml` API that feels native
-2. **Production-Ready** - Complete type support, dependency management, full test coverage
-3. **Token Efficiency** - 60% fewer tokens than JSON Schema for real workloads
-4. **Zero-Config** - Works automatically with existing Sorbet codebases
-5. **Type-Safe** - Full Sorbet type checking throughout the gem
-
-## What This Is Not
-
-- Not a BAML runtime or executor
-- Not a JSON Schema generator (use [sorbet-schema](https://github.com/maxveldink/sorbet-schema) for that)
-- Not a Sorbet type checker
-- Not a serialization library
-
-## Advanced Features
-
-### Ruby-Idiomatic API
-```ruby
-User.to_baml                    # Single type
-User.to_baml(indent_size: 4)    # Custom formatting
-User.to_baml(include_dependencies: true)  # With dependencies
-```
-
-### Automatic Dependency Management
-```ruby
-class Address < T::Struct
-  const :street, String
-end
-
-class User < T::Struct
-  const :address, Address
-end
-
-User.to_baml(include_dependencies: true)
-```
-
-**Generated BAML (correct ordering):**
-```baml
-class Address {
-  street string
-}
-
-class User {
-  address Address
-}
-```
-
-## Why BAML?
-
-BAML (Boundary AI Markup Language) provides a concise way to define types for LLM consumption. **Real-world comparison** from production agentic workflows:
-
-| Format | Tokens | Efficiency |
-|--------|--------|-----------|
-| JSON Schema | ~450 | baseline |
-| **BAML** | **~180** | **🔥 60% fewer** |
-
-### Benefits:
-- **Cost Savings**: 60% reduction in prompt tokens = 60% lower LLM API costs
-- **Performance**: Smaller prompts = faster LLM response times  
-- **Context Efficiency**: More room for actual content vs. type definitions
-- **Readability**: Human-readable and maintainable
-- **LLM-Friendly**: Designed specifically for AI consumption
-
-Perfect for prompt engineering, structured output generation, and agentic workflows where token efficiency matters.