synthra 0.1.0

data/lib/synthra/factory_bot_integration.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Synthra
+  # Factory Bot Integration
+  #
+  # Provides seamless integration between Synthra and Factory Bot.
+  # Define factories using Synthra schemas with full trait support.
+  #
+  # @example Define a factory
+  #   Synthra.define_factory(:user, schema: "User") do
+  #     trait(:admin) do
+  #       role { "admin" }
+  #     end
+  #
+  #     trait(:with_address) do
+  #       address { Synthra.generate("Address") }
+  #     end
+  #   end
+  #
+  # @example Use in tests
+  #   create(:user)
+  #   create(:user, :admin)
+  #   create(:user, :admin, :with_address, name: "Custom Name")
+  #
+  module FactoryBotIntegration
+    class << self
+      # Registry of Synthra factories
+      attr_accessor :factories
+
+      # Define a factory using a Synthra schema
+      #
+      # @param factory_name [Symbol] the factory name
+      # @param schema [String] the schema name
+      # @yield block for defining traits and overrides
+      # @return [void]
+      #
+      def define_factory(factory_name, schema:, &block)
+        @factories ||= {}
+        @factories[factory_name] = {
+          schema: schema,
+          traits: {},
+          overrides: {},
+          block: block
+        }
+
+        # Register with Factory Bot if available
+        register_with_factory_bot(factory_name, schema, &block) if factory_bot_available?
+      end
+
+      # Generate data using a defined factory
+      #
+      # @param factory_name [Symbol] the factory name
+      # @param traits [Array<Symbol>] traits to apply
+      # @param overrides [Hash] field overrides
+      # @return [Hash] generated data
+      #
+      def build(factory_name, *traits, **overrides)
+        factory = @factories&.[](factory_name)
+        raise ArgumentError, "Unknown factory: #{factory_name}" unless factory
+
+        # Get the schema
+        schema = Synthra.parse(load_schema_source(factory[:schema]))
+
+        # Apply traits
+        merged_overrides = overrides.dup
+        traits.each do |trait_name|
+          trait = factory[:traits][trait_name]
+          merged_overrides.merge!(trait) if trait
+        end
+
+        # Generate with overrides
+        schema.generate(overrides: merged_overrides)
+      end
+
+      # Check if Factory Bot is available
+      #
+      # @return [Boolean]
+      #
+      def factory_bot_available?
+        !!defined?(FactoryBot)
+      end
+
+      private
+
+      def load_schema_source(schema_name)
+        # Check if it's already a schema object or a string
+        if schema_name.is_a?(Schema)
+          return schema_name
+        end
+
+        # Try to find in default registry
+        if Synthra.instance_variable_get(:@default_registry)
+          registry = Synthra.instance_variable_get(:@default_registry)
+          return registry.schema(schema_name) if registry.schema?(schema_name)
+        end
+
+        # Create minimal DSL for the schema
+        "#{schema_name}:\n  id: uuid"
+      end
+
+      # :nocov: requires the factory_bot gem's DSL runtime (FactoryBot.define / factory / trait),
+      # which is not a dependency of this gem; exercised only inside a consuming app that has
+      # factory_bot loaded. The dispatch into here is covered (see define_factory spec).
+      def register_with_factory_bot(factory_name, schema_name, &block)
+        # Integration with Factory Bot DSL
+        factory_config = @factories[factory_name]
+
+        FactoryBot.define do
+          factory factory_name do
+            initialize_with do
+              Synthra::FactoryBotIntegration.build(
+                factory_name,
+                *@build_strategy_traits,
+                **attributes
+              )
+            end
+
+            # Process the block to extract traits
+            instance_exec(&block) if block
+          end
+        end
+      end
+      # :nocov:
+    end
+
+    # DSL methods available inside factory definition blocks
+    module DSL
+      # Define a trait for the factory
+      #
+      # @param name [Symbol] trait name
+      # @yield block that returns field overrides
+      #
+      def trait(name, &block)
+        # Store the trait for later use
+        @current_factory_traits ||= {}
+        @current_factory_traits[name] = block
+      end
+    end
+
+    # RSpec integration helpers
+    module RSpec
+      # Include Synthra factory support in RSpec
+      #
+      # @example In spec_helper.rb
+      #   require 'synthra/factory_bot_integration'
+      #   RSpec.configure do |config|
+      #     config.include Synthra::FactoryBotIntegration::RSpec
+      #   end
+      #
+      def fake_data_build(factory_name, *traits, **overrides)
+        FactoryBotIntegration.build(factory_name, *traits, **overrides)
+      end
+
+      alias build_fake_data fake_data_build
+    end
+  end
+end

data/lib/synthra/field.rb

@@ -0,0 +1,440 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Field and FieldBehavior Classes
+# =============================================================================
+#
+# This file defines the Field class which represents a single field in a
+# schema, and the FieldBehavior class for field-level behaviors.
+#
+# Fields are created during DSL parsing and contain all information needed
+# to generate values: type, arguments, modifiers, and behaviors.
+#
+# @example Field in DSL
+#   User:
+#     name: text                    # Simple field
+#     age: number(18..80)           # Field with arguments
+#     email?: email                 # Optional field (? suffix)
+#     status: enum(active, inactive) @partial_data 20%  # Field with behavior
+#
+# =============================================================================
+
+
+module Synthra
+
+  # Represents a single field in a schema definition
+  #
+  # A Field encapsulates all information about a schema field including:
+  # - Field name and whether it's optional
+  # - Type name and arguments for generation
+  # - Nullable status (can the value be nil?)
+  # - Conditional expression (when should this field be included?)
+  # - Field-level behaviors (latency, partial_data, etc.)
+  #
+  # @example Create a field programmatically
+  #   field = Field.new(
+  #     name: "email",
+  #     type_name: "email",
+  #     type_args: { domain: "example.com" },
+  #     nullable: false
+  #   )
+  #
+  # @example Optional field (from DSL: "nickname?: text")
+  #   field = Field.new(name: "nickname?", type_name: "text")
+  #   field.name        # => "nickname"
+  #   field.optional?   # => true
+  #
+  # @example Nullable type (from DSL: "manager: User?")
+  #   field = Field.new(name: "manager", type_name: "User?")
+  #   field.nullable?   # => true
+  #
+
+  class Field
+
+    # @!attribute [r] name
+    #   The field name (without ? suffix)
+    #   @return [String] the clean field name
+
+    attr_reader :name
+
+
+    # @!attribute [r] type_name
+    #   The type name (without ? suffix)
+    #   @return [String] the clean type name
+
+    attr_reader :type_name
+
+
+    # @!attribute [r] type_args
+    #   Arguments passed to the type generator
+    #   @return [Hash] type arguments (e.g., { min: 0, max: 100 })
+
+    attr_reader :type_args
+
+
+    # @!attribute [r] condition
+    #   Field name for conditional inclusion
+    #   @return [String, nil] the condition field name, or nil if unconditional
+
+    attr_reader :condition
+
+
+    # @!attribute [r] behaviors
+    #   Field-level behaviors (latency, partial_data, etc.)
+    #   @return [Array<FieldBehavior>] list of field behaviors
+
+    attr_reader :behaviors
+
+
+    # Create a new Field instance
+    #
+    # @param name [String] field name (may include ? suffix for optional)
+    # @param type_name [String] the type name (may include ? suffix for nullable)
+    # @param type_args [Hash] arguments to pass to the type generator
+    # @param nullable [Boolean] whether the field value can be nil
+    # @param condition [String, nil] field name that must be truthy for inclusion
+    # @param behaviors [Array<FieldBehavior>] field-level behaviors to apply
+    #
+    # @example Simple field
+    #   Field.new(name: "id", type_name: "uuid")
+    #
+    # @example Field with arguments
+    #   Field.new(
+    #     name: "age",
+    #     type_name: "number",
+    #     type_args: { min: 18, max: 80 }
+    #   )
+    #
+    # @example Optional nullable field with condition
+    #   Field.new(
+    #     name: "manager?",
+    #     type_name: "User?",
+    #     condition: "is_employee"
+    #   )
+    #
+
+    def initialize(name:, type_name:, type_args: {}, nullable: false, condition: nil, behaviors: [])
+      @raw_name = name
+      @name = name.delete_suffix("?")
+      @optional = name.end_with?("?")
+      @type_name = type_name.to_s.delete_suffix("?")
+      @type_args = type_args || {}
+      @nullable = nullable || type_name.to_s.end_with?("?")
+      @condition = condition
+      @behaviors = behaviors
+    end
+
+
+    # Check if this field is optional
+    #
+    # Optional fields (marked with ? suffix in DSL) may be omitted from
+    # the generated output entirely based on configuration or randomness.
+    #
+    # @return [Boolean] true if the field is optional
+    #
+    # @example
+    #   Field.new(name: "nickname?", type_name: "text").optional?  # => true
+    #   Field.new(name: "name", type_name: "text").optional?       # => false
+    #
+
+    def optional?
+      @optional
+    end
+
+
+    # Check if this field's type is nullable
+    #
+    # Nullable types (marked with ? suffix on type in DSL) can generate
+    # nil values. This is different from optional - nullable fields are
+    # always included but may have nil values.
+    #
+    # @return [Boolean] true if the type can be nil
+    #
+    # @example
+    #   Field.new(name: "manager", type_name: "User?").nullable?  # => true
+    #   Field.new(name: "manager", type_name: "User").nullable?   # => false
+    #
+
+    def nullable?
+      @nullable
+    end
+
+
+    # Check if this field has a condition
+    #
+    # Conditional fields are only included when another field has a truthy
+    # value. The condition is specified with "if field_name" in the DSL.
+    #
+    # @return [Boolean] true if the field has a condition
+    #
+    # @example DSL: "admin_note: text if is_admin"
+    #   field.conditional?  # => true
+    #   field.condition     # => "is_admin"
+    #
+
+    def conditional?
+      !condition.nil?
+    end
+
+
+    # Check if this field has a uniqueness constraint
+    #
+    # Unique fields will not generate duplicate values within a batch.
+    # The generator will retry up to max_unique_retries times.
+    #
+    # @return [Boolean] true if the field requires unique values
+    #
+    # @example DSL: "id: uuid unique"
+    #   field.unique?  # => true
+    #
+
+    def unique?
+      type_args[:unique] == true
+    end
+
+
+    # Get the range constraint if present
+    #
+    # Range constraints limit the generated values to a specific range.
+    # Common for number types.
+    #
+    # @return [Range, nil] the range constraint, or nil if not specified
+    #
+    # @example DSL: "age: number(18..80)"
+    #   field.range  # => 18..80
+    #
+
+    def range
+      return nil unless type_args[:range]
+
+      type_args[:range]
+    end
+
+
+    # Check if this field has a specific behavior
+    #
+    # @param type [Symbol, String] the behavior type to check for
+    # @return [Boolean] true if the field has the specified behavior
+    #
+    # @example
+    #   field.has_behavior?(:latency)       # => true
+    #   field.has_behavior?(:partial_data)  # => false
+    #
+
+    def has_behavior?(type)
+      behaviors.any? { |b| b.type == type.to_sym }
+    end
+
+
+    # Get a specific behavior by type
+    #
+    # @param type [Symbol, String] the behavior type to retrieve
+    # @return [FieldBehavior, nil] the behavior or nil if not found
+    #
+    # @example
+    #   behavior = field.behavior(:latency)
+    #   behavior.value  # => { min: 100, max: 500 }
+    #
+
+    def behavior(type)
+      behaviors.find { |b| b.type == type.to_sym }
+    end
+
+
+    # Get all modifiers as a hash
+    #
+    # Returns a hash containing all field modifiers (unique, range,
+    # nullable, optional) with their values, excluding nil values.
+    #
+    # @return [Hash] modifier name => value pairs
+    #
+    # @example
+    #   field.modifiers
+    #   # => { unique: true, nullable: false, optional: true }
+    #
+
+    def modifiers
+      {
+        unique: unique?,
+        range: range,
+        nullable: nullable?,
+        optional: optional?
+      }.compact
+    end
+
+
+    # String representation of the field
+    #
+    # Returns a human-readable string showing the field definition
+    # similar to how it would appear in a DSL file.
+    #
+    # @return [String] string representation
+    #
+    # @example
+    #   field.to_s  # => "name: text"
+    #   field.to_s  # => "age: number({min: 18, max: 80})"
+    #
+
+    def to_s
+      parts = ["#{@raw_name}: #{type_name}"]
+      parts << "(#{type_args})" unless type_args.empty?
+      parts << "if #{condition}" if condition
+      behaviors.each { |b| parts << "@#{b.type} #{b.value}" }
+      parts.join(" ")
+    end
+
+
+    # Inspect representation for debugging
+    #
+    # @return [String] inspect string
+    #
+
+    def inspect
+      "#<Field #{self}>"
+    end
+  end
+
+
+  # Represents a field-level behavior
+  #
+  # Field behaviors modify how individual fields are generated or returned.
+  # They can add latency, omit data, or apply other transformations to
+  # specific fields rather than the entire schema.
+  #
+  # @example DSL field with behavior
+  #   # User:
+  #   #   profile_image: url @partial_data 30%   # 30% chance of null
+  #   #   bio: text @latency 100..500ms          # 100-500ms delay
+  #
+  # @example Create a field behavior programmatically
+  #   behavior = FieldBehavior.new(
+  #     type: :latency,
+  #     value: { min: 100, max: 500 }
+  #   )
+  #
+
+  class FieldBehavior
+
+    # @!attribute [r] type
+    #   The behavior type (:latency, :partial_data, etc.)
+    #   @return [Symbol] behavior type
+
+    attr_reader :type
+
+
+    # @!attribute [r] value
+    #   The behavior configuration value
+    #   @return [Integer, Range, Hash] behavior value/configuration
+
+    attr_reader :value
+
+
+    # Create a new FieldBehavior
+    #
+    # @param type [Symbol, String] behavior type (:partial_data, :latency, etc.)
+    # @param value [Integer, Range, Hash] behavior configuration
+    #
+    # @example Percentage-based behavior
+    #   FieldBehavior.new(type: :partial_data, value: 30)
+    #
+    # @example Range-based behavior
+    #   FieldBehavior.new(type: :latency, value: { min: 100, max: 500 })
+    #
+
+    def initialize(type:, value:)
+      @type = type.to_sym
+      @value = value
+    end
+
+
+    # Get the behavior value as a percentage
+    #
+    # For probability-based behaviors, extracts the percentage value
+    # from various value formats.
+    #
+    # @return [Integer] the percentage (0-100)
+    #
+    # @example
+    #   FieldBehavior.new(type: :partial_data, value: 30).percentage
+    #   # => 30
+    #
+    #   FieldBehavior.new(type: :partial_data, value: { probability: 25 }).percentage
+    #   # => 25
+    #
+
+    def percentage
+      case value
+      when Integer then value
+      when Hash then value[:percent] || value[:probability] || 0
+      else 0
+      end
+    end
+
+
+    # Get the behavior value as a range
+    #
+    # For range-based behaviors (like latency), converts various value
+    # formats into a Range object.
+    #
+    # @return [Range] the range
+    #
+    # @example
+    #   FieldBehavior.new(type: :latency, value: 100..500).range
+    #   # => 100..500
+    #
+    #   FieldBehavior.new(type: :latency, value: { min: 100, max: 500 }).range
+    #   # => 100..500
+    #
+    #   FieldBehavior.new(type: :latency, value: 100).range
+    #   # => 100..100
+    #
+
+    def range
+      case value
+      when Range then value
+      when Hash
+        min = value[:min] || 0
+        max = value[:max] || min
+        min..max
+      else
+        value..value
+      end
+    end
+
+
+    # String representation
+    #
+    # @return [String] string like "@latency 100..500"
+    #
+
+    def to_s
+      "@#{type} #{value}"
+    end
+
+
+    # Inspect representation
+    #
+    # @return [String] inspect string
+    #
+
+    def inspect
+      "#<FieldBehavior #{self}>"
+    end
+
+
+    # Check equality with another FieldBehavior
+    #
+    # Two behaviors are equal if they have the same type and value.
+    #
+    # @param other [FieldBehavior] the other behavior to compare
+    # @return [Boolean] true if equal
+    #
+
+    def ==(other)
+      return false unless other.is_a?(FieldBehavior)
+
+      type == other.type && value == other.value
+    end
+  end
+end

data/lib/synthra/functions/registry.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Synthra
+  module Functions
+
+    # Registry for custom functions used in computed fields
+    class Registry
+      @functions = {}
+      @mutex = Mutex.new
+
+      class << self
+
+        # Register a custom function
+        #
+        # @param name [Symbol] function name
+        # @param force [Boolean] allow overwriting existing function
+        # @yield [context] block that computes the value
+        # @return [void]
+        # @raise [ArgumentError] if function exists and force is false
+
+        def register(name, force: false, &block)
+          @mutex.synchronize do
+            key = name.to_sym
+            if @functions.key?(key) && !force
+              raise ArgumentError, "Function '#{name}' already registered. Use force: true to override."
+            end
+
+            @functions[key] = block
+          end
+        end
+
+
+        # Lookup a registered function
+        #
+        # @param name [Symbol] function name
+        # @return [Proc]
+        # @raise [MissingFunctionError] if not found
+
+        def lookup(name)
+          @mutex.synchronize do
+            @functions.fetch(name.to_sym) do
+              raise MissingFunctionError, name
+            end
+          end
+        end
+
+
+        # Call a registered function
+        #
+        # @param name [Symbol] function name
+        # @param context [Context] generation context
+        # @return [Object] result
+
+        def call(name, context)
+          func = lookup(name)
+          func.call(context)
+        end
+
+
+        # Check if a function is registered
+        #
+        # @param name [Symbol] function name
+        # @return [Boolean]
+
+        def registered?(name)
+          @mutex.synchronize do
+            @functions.key?(name.to_sym)
+          end
+        end
+
+
+        # List all registered function names
+        #
+        # @return [Array<Symbol>]
+
+        def names
+          @mutex.synchronize { @functions.keys }
+        end
+
+
+        # Clear all registered functions
+        #
+        # @return [void]
+
+        def clear
+          @mutex.synchronize { @functions.clear }
+        end
+
+
+        # Unregister a specific function
+        #
+        # @param name [Symbol] function name
+        # @return [Proc, nil] the removed function
+
+        def unregister(name)
+          @mutex.synchronize do
+            @functions.delete(name.to_sym)
+          end
+        end
+      end
+    end
+  end
+end
+