sorbet-toon 0.1.0

data/lib/sorbet/toon/reconstructor.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'sorbet-runtime'
+
+module Sorbet
+  module Toon
+    module Reconstructor
+      class << self
+        def reconstruct(value, signature: nil, struct_class: nil, role: :output)
+          target_class = struct_class || resolve_struct_class(signature, role)
+          return value unless target_class
+
+          convert_hash_to_struct(value, target_class)
+        end
+
+        private
+
+        def resolve_struct_class(signature, role)
+          return nil unless signature
+
+          case role
+          when :input
+            signature.input_struct_class
+          else
+            signature.output_struct_class
+          end
+        end
+
+        def convert_hash_to_struct(hash, struct_class)
+          return hash unless hash.is_a?(Hash)
+
+          attributes = {}
+
+          struct_class.props.each do |prop_name, prop_info|
+            raw_value = fetch_value(hash, prop_name)
+            next if raw_value.nil?
+
+            type_object = prop_info[:type_object] || T::Utils.coerce(prop_info[:type])
+            attributes[prop_name] = convert_value(raw_value, type_object)
+          end
+
+          struct_class.new(**attributes)
+        rescue StandardError
+          hash
+        end
+
+        def fetch_value(hash, prop_name)
+          key = prop_name.to_s
+          return hash[key] if hash.key?(key)
+          return hash[prop_name] if hash.key?(prop_name)
+
+          sym_key = key.to_sym
+          hash[sym_key] if hash.key?(sym_key)
+        end
+
+        def convert_value(value, type_object)
+          return nil if value.nil?
+          return value unless type_object
+
+          case type_object
+          when T::Types::TypedArray
+            convert_typed_array(value, type_object)
+          when T::Types::TypedSet
+            convert_typed_set(value, type_object)
+          when T::Types::TypedHash
+            convert_typed_hash(value, type_object)
+          when T::Types::Simple
+            convert_simple(value, type_object)
+          when T::Types::Union
+            convert_union(value, type_object)
+          else
+            value
+          end
+        end
+
+        def convert_simple(value, simple_type)
+          raw = simple_type.raw_type
+          return convert_hash_to_struct(value, raw) if struct_class?(raw) && value.is_a?(Hash)
+          return deserialize_enum(raw, value) if enum_class?(raw) && !value.is_a?(raw)
+
+          value
+        end
+
+        def convert_typed_array(value, typed_array)
+          return value unless value.is_a?(Array)
+
+          value.map { |element| convert_value(element, typed_array.type) }
+        end
+
+        def convert_typed_set(value, typed_set)
+          return value unless value.is_a?(Array)
+
+          Set.new(value.map { |element| convert_value(element, typed_set.type) })
+        end
+
+        def convert_typed_hash(value, typed_hash)
+          return value unless value.is_a?(Hash)
+
+          value.each_with_object({}) do |(key, val), memo|
+            converted_key = coerce_hash_key(key, typed_hash.keys)
+            memo[converted_key] = convert_value(val, typed_hash.values)
+          end
+        end
+
+        def convert_union(value, union_type)
+          return nil if value.nil? && union_type.types.any? { |member| nil_type?(member) }
+
+          if value.is_a?(Hash)
+            explicit_type = union_struct_from_type_field(value, union_type)
+            return convert_value(value, explicit_type) if explicit_type
+          end
+
+          union_type.types.each do |member|
+            next if nil_type?(member)
+
+            converted = convert_value(value, member)
+            return converted unless converted.equal?(value)
+          end
+
+          value
+        end
+
+        def union_struct_from_type_field(hash, union_type)
+          type_name = hash['_type'] || hash[:_type]
+          return nil unless type_name
+
+          union_type.types.find do |member|
+            struct_type?(member) && struct_name(member.raw_type) == type_name
+          end
+        end
+
+        def struct_type?(type)
+          type.is_a?(T::Types::Simple) && struct_class?(type.raw_type)
+        end
+
+        def nil_type?(type)
+          type.is_a?(T::Types::Simple) && type.raw_type == NilClass
+        end
+
+        def struct_class?(klass)
+          klass.is_a?(Class) && klass < T::Struct
+        rescue StandardError
+          false
+        end
+
+        def enum_class?(klass)
+          klass.is_a?(Class) && klass < T::Enum
+        rescue StandardError
+          false
+        end
+
+        def deserialize_enum(enum_class, value)
+          return value if value.is_a?(enum_class)
+          return enum_class.deserialize(value) if enum_class.respond_to?(:deserialize)
+
+          enum_class.values.find { |member| member.serialize == value } || value
+        end
+
+        def coerce_hash_key(key, key_type)
+          return key unless key_type.is_a?(T::Types::Simple)
+
+          case key_type.raw_type
+          when Symbol
+            key.to_sym
+          when Integer
+            key.to_i
+          when Float
+            key.to_f
+          else
+            key.to_s
+          end
+        end
+
+        def struct_name(klass)
+          klass.name&.split('::')&.last
+        end
+      end
+    end
+  end
+end

data/lib/sorbet/toon/shared/literal_utils.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../constants'
+
+module Sorbet
+  module Toon
+    module Shared
+      module LiteralUtils
+        module_function
+
+        def boolean_or_null_literal?(token)
+          return false if token.nil?
+
+          token == Constants::TRUE_LITERAL ||
+            token == Constants::FALSE_LITERAL ||
+            token == Constants::NULL_LITERAL
+        end
+
+        def numeric_literal?(token)
+          return false if token.nil? || token.empty?
+
+          # Reject numbers with leading zeros (except 0.x cases)
+          if token.length > 1 && token.start_with?('0') && token[1] != '.'
+            return false
+          end
+
+          numeric_value = Float(token)
+          numeric_value.finite?
+        rescue ArgumentError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/sorbet/toon/shared/string_utils.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative '../constants'
+require_relative '../errors'
+
+module Sorbet
+  module Toon
+    module Shared
+      module StringUtils
+        module_function
+
+        def escape_string(value)
+          value
+            .gsub('\\') { Constants::BACKSLASH * 2 }
+            .gsub('"', "#{Constants::BACKSLASH}#{Constants::DOUBLE_QUOTE}")
+            .gsub("\n", "#{Constants::BACKSLASH}n")
+            .gsub("\r", "#{Constants::BACKSLASH}r")
+            .gsub("\t", "#{Constants::BACKSLASH}t")
+        end
+
+        def unescape_string(value)
+          result = +''
+          i = 0
+          while i < value.length
+            char = value[i]
+            if char == Constants::BACKSLASH
+              raise Sorbet::Toon::DecodeError, 'Invalid escape sequence: backslash at end of string' if i + 1 >= value.length
+
+              next_char = value[i + 1]
+              case next_char
+              when 'n'
+                result << Constants::NEWLINE
+              when 't'
+                result << Constants::TAB
+              when 'r'
+                result << Constants::CARRIAGE_RETURN
+              when Constants::BACKSLASH
+                result << Constants::BACKSLASH
+              when Constants::DOUBLE_QUOTE
+                result << Constants::DOUBLE_QUOTE
+              else
+                raise Sorbet::Toon::DecodeError, "Invalid escape sequence: \\#{next_char}"
+              end
+              i += 2
+              next
+            end
+
+            result << char
+            i += 1
+          end
+          result
+        end
+
+        def find_closing_quote(content, start_index)
+          i = start_index + 1
+          while i < content.length
+            if content[i] == Constants::BACKSLASH && i + 1 < content.length
+              i += 2
+              next
+            end
+
+            return i if content[i] == Constants::DOUBLE_QUOTE
+
+            i += 1
+          end
+          -1
+        end
+
+        def find_unquoted_char(content, char, start_index = 0)
+          in_quotes = false
+          i = start_index
+
+          while i < content.length
+            if content[i] == Constants::BACKSLASH && i + 1 < content.length && in_quotes
+              i += 2
+              next
+            end
+
+            if content[i] == Constants::DOUBLE_QUOTE
+              in_quotes = !in_quotes
+              i += 1
+              next
+            end
+
+            return i if content[i] == char && !in_quotes
+
+            i += 1
+          end
+
+          -1
+        end
+      end
+    end
+  end
+end

data/lib/sorbet/toon/shared/validation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative '../constants'
+require_relative 'literal_utils'
+
+module Sorbet
+  module Toon
+    module Shared
+      module Validation
+        module_function
+
+        UNQUOTED_KEY_REGEX = /\A[A-Z_][\w.]*\z/i.freeze
+        NUMERIC_LIKE_REGEX = /\A-?\d+(?:\.\d+)?(?:e[+-]?\d+)?\z/i.freeze
+        LEADING_ZERO_REGEX = /\A0\d+\z/.freeze
+
+        def valid_unquoted_key?(key)
+          UNQUOTED_KEY_REGEX.match?(key)
+        end
+
+        def safe_unquoted?(value, delimiter = Constants::COMMA)
+          return false if value.nil? || value.empty?
+          return false if value != value.strip
+          return false if LiteralUtils.boolean_or_null_literal?(value) || numeric_like?(value)
+          return false if value.include?(Constants::COLON)
+          return false if value.include?(Constants::DOUBLE_QUOTE) || value.include?(Constants::BACKSLASH)
+          return false if value.match?(/[{}\[\]]/)
+          return false if value.match?(/[\n\r\t]/)
+          return false if value.include?(delimiter)
+          return false if value.start_with?(Constants::LIST_ITEM_MARKER)
+
+          true
+        end
+
+        def numeric_like?(value)
+          NUMERIC_LIKE_REGEX.match?(value) || LEADING_ZERO_REGEX.match?(value)
+        end
+        private_class_method :numeric_like?
+      end
+    end
+  end
+end

data/lib/sorbet/toon/signature_formatter.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module Sorbet
+  module Toon
+    module SignatureFormatter
+      module_function
+
+      def describe_signature(signature_class, role)
+        struct_class = struct_for(signature_class, role)
+        return "No #{role} fields defined." unless struct_class
+
+        descriptors = field_descriptors(signature_class, role)
+        describe_struct(struct_class, descriptors)
+      end
+
+      def struct_for(signature_class, role)
+        return nil unless signature_class
+
+        case role
+        when :input
+          signature_class.input_struct_class if signature_class.respond_to?(:input_struct_class)
+        else
+          signature_class.output_struct_class if signature_class.respond_to?(:output_struct_class)
+        end
+      end
+      private_class_method :struct_for
+
+      def field_descriptors(signature_class, role)
+        return {} unless signature_class
+
+        case role
+        when :input
+          signature_class.respond_to?(:input_field_descriptors) ? signature_class.input_field_descriptors || {} : {}
+        else
+          signature_class.respond_to?(:output_field_descriptors) ? signature_class.output_field_descriptors || {} : {}
+        end
+      end
+      private_class_method :field_descriptors
+
+      def describe_struct(struct_class, descriptors)
+        lines = []
+
+        struct_class.props.each do |prop_name, prop_info|
+          descriptor = descriptors[prop_name]
+          type_object = descriptor&.type || prop_info[:type_object] || prop_info[:type]
+          type_info = describe_type(type_object)
+          optional = descriptor&.has_default || prop_info[:fully_optional]
+
+          line = "- #{prop_name}"
+          type_label = type_info[:label]
+          line << " (#{type_label}"
+          line << ', optional' if optional
+          line << ')'
+          if descriptor&.description
+            line << " — #{descriptor.description}"
+          end
+
+          lines << line
+
+          if type_info[:tabular_columns]
+            lines << "    • Tabular columns: #{type_info[:tabular_columns].join(', ')}"
+          end
+        end
+
+        return "No fields defined." if lines.empty?
+
+        lines.join("\n")
+      end
+      private_class_method :describe_struct
+
+      def describe_type(type)
+        case type
+        when T::Types::TypedArray
+          inner = describe_type(type.type)
+          {
+            label: "Array<#{inner[:label]}>",
+            tabular_columns: inner[:tabular_columns]
+          }
+        when T::Types::TypedSet
+          inner = describe_type(type.type)
+          {
+            label: "Set<#{inner[:label]}>"
+          }
+        when T::Types::TypedHash
+          key = describe_type(type.keys)
+          value = describe_type(type.values)
+          {
+            label: "Hash<#{key[:label]} => #{value[:label]}>"
+          }
+        when T::Types::Union
+          members = type.types.reject { |member| nil_type?(member) }
+          labels = members.map { |member| describe_type(member)[:label] }.uniq
+          { label: labels.join(' | ') }
+        when T::Private::Types::TypeAlias
+          describe_type(type.aliased_type)
+        when T::Types::Simple
+          describe_class(type.raw_type)
+        when Class
+          describe_class(type)
+        else
+          { label: type_label_from_object(type) }
+        end
+      end
+      private_class_method :describe_type
+
+      def describe_class(klass)
+        return { label: 'nil' } if klass.nil?
+
+        if struct_class?(klass)
+          {
+            label: klass.name ? klass.name.split('::').last : 'Struct',
+            tabular_columns: klass.props.keys.map(&:to_s)
+          }
+        elsif enum_class?(klass)
+          values = klass.respond_to?(:values) ? klass.values.map(&:serialize).join(', ') : ''
+          { label: values.empty? ? klass.name || 'Enum' : "Enum<#{values}>" }
+        else
+          { label: primitive_label(klass) }
+        end
+      end
+      private_class_method :describe_class
+
+      def primitive_label(klass)
+        case klass.name
+        when 'String' then 'String'
+        when 'Integer' then 'Integer'
+        when 'Float' then 'Float'
+        when 'TrueClass', 'FalseClass' then 'Boolean'
+        when 'Numeric' then 'Number'
+        when 'Date' then 'Date'
+        when 'DateTime', 'Time' then 'DateTime'
+        else
+          klass.name || klass.to_s
+        end
+      end
+      private_class_method :primitive_label
+
+      def type_label_from_object(type)
+        if type.respond_to?(:name)
+          type.name
+        else
+          type.to_s
+        end
+      end
+      private_class_method :type_label_from_object
+
+      def struct_class?(klass)
+        klass.is_a?(Class) && klass < T::Struct
+      rescue StandardError
+        false
+      end
+      private_class_method :struct_class?
+
+      def enum_class?(klass)
+        klass.is_a?(Class) && klass < T::Enum
+      rescue StandardError
+        false
+      end
+      private_class_method :enum_class?
+
+      def nil_type?(type)
+        (type.is_a?(T::Types::Simple) && type.raw_type == NilClass) ||
+          type == T::Utils.coerce(NilClass)
+      rescue StandardError
+        false
+      end
+      private_class_method :nil_type?
+    end
+  end
+end

data/lib/sorbet/toon/struct_extensions.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Sorbet
+  module Toon
+    module StructExtensions
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def from_toon(payload, **options)
+          Sorbet::Toon.decode(payload, struct_class: self, **options)
+        end
+      end
+
+      def to_toon(**options)
+        Sorbet::Toon.encode(self, **options)
+      end
+    end
+  end
+end

data/lib/sorbet/toon/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Sorbet
+  module Toon
+    VERSION = '0.1.0'
+  end
+end

data/lib/sorbet/toon.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+require_relative 'toon/version'
+require_relative 'toon/errors'
+require_relative 'toon/constants'
+require_relative 'toon/codec'
+require_relative 'toon/normalizer'
+require_relative 'toon/config'
+require_relative 'toon/encoder'
+require_relative 'toon/decoder'
+require_relative 'toon/reconstructor'
+require_relative 'toon/signature_formatter'
+require_relative 'toon/struct_extensions'
+require_relative 'toon/enum_extensions'
+
+module Sorbet
+  module Toon
+    class << self
+      def encode(value, **options)
+        Encoder.encode(value, config: config, **options)
+      end
+
+      def decode(payload, struct_class: nil, **options)
+        Decoder.decode(payload, config: config, struct_class: struct_class, **options)
+      end
+
+      def configure
+        yield(config)
+      end
+
+      def config
+        @config ||= Config.new
+      end
+
+      def reset_config!(new_config = nil)
+        @config = new_config&.copy || Config.new
+      end
+
+      def enable_extensions!
+        return if extensions_enabled?
+
+        T::Struct.include(Sorbet::Toon::StructExtensions)
+        T::Enum.include(Sorbet::Toon::EnumExtensions)
+        @extensions_enabled = true
+      end
+
+      def extensions_enabled?
+        !!@extensions_enabled
+      end
+    end
+  end
+end
+
+Sorbet::Toon.enable_extensions!

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: sorbet-toon
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vicente Reig Rincón de Arellano
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+description: Ruby port of the TOON encoder/decoder used inside DSPy.rb. Provides Sorbet-aware
+  normalization, reconstruction, and prompt-ready helpers so signatures can round-trip
+  through TOON without hand-written serializers.
+email:
+- hey@vicente.services
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- lib/sorbet/toon.rb
+- lib/sorbet/toon/README.md
+- lib/sorbet/toon/codec.rb
+- lib/sorbet/toon/config.rb
+- lib/sorbet/toon/constants.rb
+- lib/sorbet/toon/decode/decoders.rb
+- lib/sorbet/toon/decode/parser.rb
+- lib/sorbet/toon/decode/scanner.rb
+- lib/sorbet/toon/decode/validation.rb
+- lib/sorbet/toon/decoder.rb
+- lib/sorbet/toon/encode/encoders.rb
+- lib/sorbet/toon/encode/normalize.rb
+- lib/sorbet/toon/encode/primitives.rb
+- lib/sorbet/toon/encode/writer.rb
+- lib/sorbet/toon/encoder.rb
+- lib/sorbet/toon/enum_extensions.rb
+- lib/sorbet/toon/errors.rb
+- lib/sorbet/toon/normalizer.rb
+- lib/sorbet/toon/reconstructor.rb
+- lib/sorbet/toon/shared/literal_utils.rb
+- lib/sorbet/toon/shared/string_utils.rb
+- lib/sorbet/toon/shared/validation.rb
+- lib/sorbet/toon/signature_formatter.rb
+- lib/sorbet/toon/struct_extensions.rb
+- lib/sorbet/toon/version.rb
+homepage: https://github.com/vicentereig/dspy.rb/blob/main/lib/sorbet/toon/README.md
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/vicentereig/dspy.rb/blob/main/lib/sorbet/toon/README.md
+  documentation_uri: https://github.com/vicentereig/dspy.rb/blob/main/lib/sorbet/toon/README.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: TOON encode/decode pipeline for Sorbet signatures.
+test_files: []