sorbet-baml 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '087824d783258689f016d3fe337fe9cfe445715f175a7d56c2ea7d6e9439b60b'
-  data.tar.gz: 273faf0407c8fec863e7efa412d0060659a9f4de85b0658024c73dfc33c88363
+  metadata.gz: eb876085f297285bbd07f7fd02c272417eade6ee6a33bd23632652746b1261d3
+  data.tar.gz: 8053e7074130ab128679fbc7a6c88d97fd2f3aaafb5c1637ab98271025fcdf69
 SHA512:
-  metadata.gz: d2d2aaae155fb4f4b0747de8ba2cbaf39d6ef97d1698b6dbf14968b4e3a6b935c59ed20a88643da333291fbbdf5d6e622a04beccc9c46887e2fc1c6a3bcd436d
-  data.tar.gz: 444968d3450fcd2776f3dac4618d59f8a76ba4032669335cbbe269eb3bbf92d63ea1f1b0eae989e432e1b601978625bb8830c23d7656bae76396c5a46a915e3c
+  metadata.gz: cb1ef5173f16930f836eac60d64ca3c3e7a98de3b1aed127012f46497b72c09fade60b34d55e9aee40e8966db3d38361706c6d9c5bdb31a1f4af7761501263c6
+  data.tar.gz: 695791bb1caee6b763437aa5f5d6688640f5792a482372eb08a5e3da74ce7a007aed166f130945b736bc47bc4030d50a24c38910b99543b5d1ea533538a31119

data/CLAUDE.md

@@ -0,0 +1,94 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+**Running Tests:**
+```bash
+bundle exec rspec                    # Run all tests
+bundle exec rspec spec/path_spec.rb  # Run specific test file
+```
+
+**Type Checking:**
+```bash
+bundle exec srb tc                   # Run Sorbet type checker
+```
+
+**Development Setup:**
+```bash
+bundle install                       # Install dependencies
+bundle exec tapioca dsl             # Generate RBI files for gems
+bundle exec tapioca gem             # Generate RBI files for dependencies
+```
+
+**Linting:**
+```bash
+bundle exec rubocop                  # Run RuboCop linter
+bundle exec rubocop -a              # Auto-fix violations where possible
+```
+
+**Gem Tasks:**
+```bash
+bundle exec rake build              # Build the gem
+bundle exec rake install            # Install locally
+bundle exec rake release            # Release to RubyGems (maintainers only)
+```
+
+## Code Architecture
+
+### Core Components
+
+**Main Library Entry Point:**
+- `lib/sorbet_baml.rb` - Main module with public API methods and extension loading
+
+**Core Conversion System:**
+- `lib/sorbet_baml/converter.rb` - Main converter orchestrating BAML generation
+- `lib/sorbet_baml/type_mapper.rb` - Maps Sorbet type objects to BAML type strings
+- `lib/sorbet_baml/dependency_resolver.rb` - Handles topological sorting of dependencies
+
+**Ruby-Idiomatic API Extensions:**
+- `lib/sorbet_baml/struct_extensions.rb` - Adds `.to_baml` method to T::Struct
+- `lib/sorbet_baml/enum_extensions.rb` - Adds `.to_baml` method to T::Enum
+
+**Field Documentation:**
+- `lib/sorbet_baml/comment_extractor.rb` - Extracts comments from source for field descriptions
+
+### Key Design Patterns
+
+**Extension Pattern:** The gem extends T::Struct and T::Enum classes with `.to_baml` methods for a Ruby-idiomatic API.
+
+**Dependency Resolution:** Uses topological sorting to ensure dependencies are output before types that reference them, preventing forward reference issues.
+
+**Type Mapping:** Comprehensive mapping from Sorbet type system to BAML types:
+- `T::Struct` → BAML classes
+- `T::Enum` → BAML enums  
+- `T.nilable(T)` → optional types (`T?`)
+- `T::Array[T]` → array types (`T[]`)
+- `T::Hash[K,V]` → map types (`map<K,V>`)
+- `T.any(T1, T2)` → union types (`T1 | T2`)
+
+**Smart Defaults:** The API includes dependencies and field descriptions by default.
+
+### Type System Support
+
+The gem provides complete coverage of Sorbet's type system:
+- Basic types (String, Integer, Float, Boolean, Symbol, Date/Time)
+- Complex types (Arrays, Hashes, Unions, Nilable)
+- Structured types (T::Struct, T::Enum with full nesting support)
+- Circular reference handling to prevent infinite loops
+
+### Testing Structure
+
+- `spec/fixtures/` - Test data including complex type examples
+- `spec/integration/` - End-to-end feature tests
+- `spec/sorbet_baml/` - Unit tests for each component
+- Comprehensive test coverage includes edge cases, circular references, and complex type combinations
+
+## Development Guidelines
+
+**Type Safety:** All code uses `# typed: strict` and maintains full Sorbet compliance.
+
+**Ruby Idioms:** The public API follows Ruby conventions with `.to_baml` instance methods rather than static factory methods.
+
+**Field Descriptions:** Comments above field definitions are automatically extracted and included as BAML `@description` annotations for LLM context.