sorbet-baml 0.1.0 → 0.3.0

data/docs/getting-started.md

@@ -1,91 +0,0 @@
-# Getting Started
-
-## Prerequisites
-
-- Ruby 3.2+
-- Sorbet installed in your project
-- Basic familiarity with T::Struct
-
-## Quick Start
-
-### 1. Define your Sorbet types
-
-```ruby
-class User < T::Struct
-  const :id, Integer
-  const :name, String
-  const :email, T.nilable(String)
-end
-```
-
-### 2. Convert to BAML
-
-```ruby
-require 'sorbet-baml'
-
-# Ruby-idiomatic API (recommended)
-User.to_baml
-
-# Legacy API (still supported)  
-baml = SorbetBaml.from_struct(User)
-puts baml
-```
-
-**Generated BAML:**
-```baml
-class User {
-  id int
-  name string
-  email string?
-}
-```
-
-### 3. Add field descriptions (optional)
-
-Document your fields with comments for better LLM understanding:
-
-```ruby
-class User < T::Struct
-  # Unique identifier for the user account
-  const :id, Integer
-  
-  # User's display name, visible to other users
-  const :name, String
-  
-  # Optional email for notifications and login
-  const :email, T.nilable(String)
-end
-
-# Generate BAML (descriptions included by default!)
-User.to_baml
-```
-
-**Generated BAML with descriptions:**
-```baml
-class User {
-  id int @description("Unique identifier for the user account")
-  name string @description("User's display name, visible to other users")
-  email string? @description("Optional email for notifications and login")
-}
-```
-
-### 4. Use with your LLM
-
-Include the BAML definition in your prompt:
-
-```ruby
-baml = User.to_baml
-prompt = <<~PROMPT
-  Generate sample data matching this schema:
-  
-  #{baml}
-  
-  Return 3 realistic examples.
-PROMPT
-```
-
-## Next Steps
-
-- [Type Mapping Reference](./type-mapping.md)
-- [Advanced Usage](./advanced-usage.md)
-- [Troubleshooting](./troubleshooting.md)

data/docs/troubleshooting.md

@@ -1,291 +0,0 @@
-# Troubleshooting
-
-## Common Issues
-
-### "undefined method `props' for Class"
-
-**Problem**: The class you're trying to convert is not a T::Struct.
-
-**Solution**: Ensure your class inherits from `T::Struct`:
-
-```ruby
-# ❌ Wrong
-class User
-  attr_reader :name
-end
-
-# ✅ Correct
-class User < T::Struct
-  const :name, String
-end
-
-# Generate BAML
-User.to_baml
-```
-
-**Generated BAML:**
-```baml
-class User {
-  name string
-}
-```
-
-### Empty output
-
-**Problem**: The struct has no properties defined.
-
-**Solution**: Define at least one property using `const` or `prop`:
-
-```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
-}
-```
-
-### 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
-
-Category.to_baml
-```
-
-**Generated BAML:**
-```baml
-class Category {
-  name string
-  parent Category?
-  children Category[]
-}
-```
-
-## Type-Specific Issues
-
-### Arrays not converting correctly
-
-Ensure you're using the Sorbet array syntax:
-
-```ruby
-# ❌ Wrong
-class User < T::Struct
-  const :items, Array  # Generic Array won't work
-end
-
-# ✅ Correct
-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
-
-Make sure to use `T.nilable`:
-
-```ruby
-# ❌ Wrong - will be required
-class User < T::Struct
-  const :email, String
-end
-
-# ✅ Correct - will be optional
-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) 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
-
-## Advanced Debugging
-
-### Inspect Sorbet type information
-
-```ruby
-# 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,192 +0,0 @@
-# Type Mapping Reference
-
-Complete mapping between Sorbet types and BAML output. All listed types are **fully supported**.
-
-## Basic Types
-
-| Sorbet Type | BAML Output | Example |
-|-------------|-------------|---------|
-| `String` | `string` | `name string` |
-| `Integer` | `int` | `age int` |
-| `Float` | `float` | `price float` |
-| `T::Boolean` | `bool` | `active bool` |
-| `NilClass` | `null` | `null` |
-| `Symbol` | `string` | `status string` |
-| `Date/DateTime/Time` | `string` | `created_at string` |
-
-## 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[Integer]` | `int[]` | `scores int[]` |
-| `T::Array[MyStruct]` | `MyStruct[]` | `addresses Address[]` |
-
-## 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
-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
-```
-
-```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)
-```
-
-## Future Enhancements (Optional)
-
-These are nice-to-have features for future versions:
-
-- `T.type_alias` → `type Name = ...`
-- Field descriptions from comments
-- Custom naming strategies (snake_case ↔ camelCase)
-- Self-referential type handling