synthra 0.1.0

data/lib/synthra/behaviors/partial_data.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Partial Data Behavior
+# =============================================================================
+#
+# Simulates incomplete data by randomly removing fields from generated records.
+# Useful for testing applications that handle partial data gracefully.
+#
+# @example DSL usage
+#   User:
+#     @partial_data 30%              # 30% chance of removing fields
+#     name: name
+#     email: email
+#
+# @example Field-level usage
+#   User:
+#     profile: object(Profile) @partial_data 20%  # 20% chance of omitting profile
+#
+# =============================================================================
+
+
+module Synthra
+  module Behaviors
+
+    # Partial data behavior - removes some fields
+    #
+    # Randomly removes fields from generated records to simulate incomplete
+    # data. Prefers removing non-critical fields (excludes "id" and "uuid").
+    #
+    # @example Apply partial data behavior
+    #   behavior = PartialData.new(30, rng)  # 30% probability
+    #   result = behavior.apply({ "id" => "1", "name" => "John", "email" => "..." })
+    #   # => { "id" => "1", "name" => "John" }  # email removed 30% of the time
+    #
+
+    class PartialData < Base
+
+      # Apply partial data behavior to result
+      #
+      # Removes a random subset of fields (approximately 30% of fields)
+      # from the result hash. Preserves critical fields like "id" and "uuid".
+      #
+      # @param result [Hash] generated record to modify
+      # @param context [Generator::Context, nil] generation context (not used)
+      # @return [Hash] result with some fields removed
+      #
+      # @example
+      #   apply({ "id" => "1", "name" => "John", "email" => "..." }, nil)
+      #   # => { "id" => "1", "name" => "John" }  # email removed
+      #
+
+      def apply(result, context = nil)
+        return result unless should_apply?
+        return result unless result.is_a?(Hash)
+
+
+        # Remove optional fields first
+        keys = result.keys.select do |k|
+
+          # Prefer removing fields that look optional
+          !%w[id uuid].include?(k.to_s)
+        end
+
+        return result if keys.empty?
+
+
+        # Remove a random subset using RNG for determinism
+        count_to_remove = (keys.length * 0.3).ceil
+        if @rng
+          to_remove = keys.shuffle(random: @rng.instance_variable_get(:@random)).take(count_to_remove)
+        else
+          to_remove = keys.sample(count_to_remove)
+        end
+        to_remove.each { |k| result.delete(k) }
+
+        result
+      end
+    end
+  end
+end
+

data/lib/synthra/behaviors/randomize_order.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Randomize Order Behavior
+# =============================================================================
+#
+# Shuffles array elements in generated records to simulate non-deterministic
+# ordering. Useful for testing applications that handle unordered data.
+#
+# @example DSL usage
+#   User:
+#     @randomize_order 50%          # 50% chance of shuffling arrays
+#     tags: array(text, 1..5)
+#
+# =============================================================================
+
+
+module Synthra
+  module Behaviors
+
+    # Randomize order behavior - shuffles arrays in result
+    #
+    # Recursively shuffles all array elements in the generated result to
+    # simulate non-deterministic ordering.
+    #
+    # @example Apply randomize order behavior
+    #   behavior = RandomizeOrder.new(50, rng)  # 50% probability
+    #   result = behavior.apply({ "tags" => ["a", "b", "c"] })
+    #   # => { "tags" => ["c", "a", "b"] }  # Shuffled 50% of the time
+    #
+
+    class RandomizeOrder < Base
+
+      # Apply randomize order behavior to result
+      #
+      # Recursively shuffles all arrays found in the result hash.
+      #
+      # @param result [Object] generated data to modify
+      # @param context [Generator::Context, nil] generation context (not used)
+      # @return [Object] result with arrays shuffled
+      #
+
+      def apply(result, context = nil)
+        return result unless should_apply?
+
+        shuffle_arrays(result)
+      end
+
+      private
+
+
+      # Recursively shuffle arrays in value
+      #
+      # Traverses the value structure and shuffles all arrays found.
+      #
+      # @param value [Object] value to process (Hash, Array, or other)
+      # @return [Object] value with arrays shuffled
+      #
+
+      def shuffle_arrays(value)
+        case value
+        when Array
+          value.map { |v| shuffle_arrays(v) }.shuffle
+        when Hash
+          value.transform_values { |v| shuffle_arrays(v) }
+        else
+          value
+        end
+      end
+    end
+  end
+end
+

data/lib/synthra/behaviors/registry.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Behaviors Registry
+# =============================================================================
+#
+# The Behaviors::Registry manages registration and lookup of behavior classes.
+# Built-in behaviors are registered automatically at gem load time.
+#
+# @example Register a custom behavior
+#   Synthra::Behaviors::Registry.register(:my_behavior, MyBehaviorClass)
+#
+# @example Register with a block
+#   Synthra::Behaviors::Registry.register(:log) do |context, result, value|
+#     puts "Generated: #{result.inspect}"
+#     result
+#   end
+#
+# =============================================================================
+
+
+module Synthra
+  module Behaviors
+
+    # Registry for behavior classes
+    #
+    # Thread-safe registry for storing and retrieving behavior implementations.
+    # Supports both class-based and block-based behavior registration.
+    #
+    # @example Look up a behavior
+    #   klass = Registry.lookup(:latency)
+    #   behavior = klass.new(100..500, rng)
+    #   behavior.apply(result)
+    #
+
+    class Registry
+
+      # Internal storage for registered behaviors
+      # @api private
+      @behaviors = {}
+
+
+      # Mutex for thread-safe access
+      # @api private
+      @mutex = Mutex.new
+
+      class << self
+
+        # Register a behavior
+        #
+        # @param name [Symbol, String] behavior name (used with @ prefix in DSL)
+        # @param klass [Class, nil] behavior class (must inherit from Base)
+        # @yield [context, result, value] block for applying behavior
+        # @yieldparam context [Generator::Context] generation context
+        # @yieldparam result [Object] generated data
+        # @yieldparam value [Object] behavior configuration value
+        # @yieldreturn [Object] modified result
+        # @return [void]
+        # @raise [ArgumentError] if neither class nor block provided
+        #
+        # @example Register with class
+        #   Registry.register(:latency, Latency)
+        #
+        # @example Register with block
+        #   Registry.register(:log) do |ctx, result, value|
+        #     puts "Generated: #{result.inspect}"
+        #     result
+        #   end
+        #
+
+        def register(name, klass = nil, &block)
+          @mutex.synchronize do
+            if block_given?
+              @behaviors[name.to_sym] = BlockBehavior.new(&block)
+            elsif klass
+              @behaviors[name.to_sym] = klass
+            else
+              raise ArgumentError, "Must provide a class or block"
+            end
+          end
+        end
+
+
+        # Look up a behavior by name
+        #
+        # @param name [Symbol, String] behavior name to look up
+        # @return [Class] behavior class (can be instantiated with new(value, rng))
+        # @raise [ArgumentError] if behavior is not registered
+        #
+        # @example
+        #   klass = Registry.lookup(:latency)
+        #   behavior = klass.new(100..500, rng)
+        #
+
+        def lookup(name)
+          @mutex.synchronize do
+            @behaviors.fetch(name.to_sym) do
+              raise ArgumentError, "Unknown behavior: #{name}"
+            end
+          end
+        end
+
+
+        # Check if a behavior is registered
+        #
+        # @param name [Symbol, String] behavior name to check
+        # @return [Boolean] true if registered
+        #
+        # @example
+        #   Registry.registered?(:latency)  # => true
+        #   Registry.registered?(:unknown)  # => false
+        #
+
+        def registered?(name)
+          @mutex.synchronize do
+            @behaviors.key?(name.to_sym)
+          end
+        end
+
+
+        # List all registered behavior names
+        #
+        # @return [Array<Symbol>] list of behavior names
+        #
+        # @example
+        #   Registry.names  # => [:latency, :failure, :partial_data, ...]
+        #
+
+        def names
+          @mutex.synchronize { @behaviors.keys }
+        end
+
+
+        # Clear all registered behaviors
+        #
+        # Primarily used for testing. After calling this, you'll need
+        # to call register_builtins! to restore built-in behaviors.
+        #
+        # @return [void]
+        #
+
+        def clear
+          @mutex.synchronize { @behaviors.clear }
+        end
+
+
+        # Register all built-in behaviors
+        #
+        # Called automatically at gem initialization. Registers the
+        # standard behaviors like latency, failure, partial_data, etc.
+        #
+        # @return [void]
+        #
+
+        def register_builtins!
+          register(:latency, Latency)
+          register(:failure, Failure)
+          register(:partial_data, PartialData)
+          register(:close_connection, CloseConnection)
+          register(:simulate_error, SimulateError)
+          register(:randomize_order, RandomizeOrder)
+          register(:deprecated, Deprecated)
+        end
+      end
+
+
+      # Wrapper for block-based behaviors
+      #
+      # Allows blocks to be used as behaviors. The wrapper creates
+      # BlockBehaviorInstance objects when instantiated.
+      #
+      # @api private
+      #
+
+      class BlockBehavior
+
+        # Create a new block behavior wrapper
+        #
+        # @yield [context, result, value] block for applying behavior
+        #
+
+        def initialize(&block)
+          @block = block
+        end
+
+
+        # Create a new instance of this block behavior
+        #
+        # @param value [Object] behavior configuration
+        # @param rng [Generator::RNG, nil] random number generator
+        # @return [BlockBehaviorInstance] behavior instance
+        #
+
+        def new(value, rng = nil)
+          BlockBehaviorInstance.new(value, rng, @block)
+        end
+      end
+
+
+      # Instance of a block-based behavior
+      #
+      # Wraps a block in a Base-compatible interface.
+      #
+      # @api private
+      #
+
+      class BlockBehaviorInstance < Base
+
+        # Create a new block behavior instance
+        #
+        # @param value [Object] behavior configuration
+        # @param rng [Generator::RNG, nil] random number generator
+        # @param block [Proc] the block to call when applying
+        #
+
+        def initialize(value, rng, block)
+          super(value, rng)
+          @block = block
+        end
+
+
+        # Apply the block behavior
+        #
+        # @param result [Object] generated data
+        # @param context [Generator::Context, nil] generation context
+        # @return [Object] result from block
+        #
+
+        def apply(result, context = nil)
+          return result unless should_apply?
+
+          @block.call(context, result, value)
+        end
+      end
+    end
+  end
+end

data/lib/synthra/behaviors/simulate_error.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Simulate Error Behavior
+# =============================================================================
+#
+# Simulates HTTP-like errors by raising SimulatedError exception with
+# a specified error code. Useful for testing error handling logic.
+#
+# @example DSL usage
+#   User:
+#     @simulate_error 500 10%        # 10% chance of 500 error
+#     @simulate_error 404 5%         # 5% chance of 404 error
+#     name: name
+#
+# =============================================================================
+
+
+module Synthra
+  module Behaviors
+
+    # Simulate error behavior - raises HTTP-like error
+    #
+    # Raises SimulatedError exception with a specified HTTP status code
+    # when activated, simulating API errors.
+    #
+    # @example Apply simulate error behavior
+    #   behavior = SimulateError.new(500, rng)  # 500 error
+    #   begin
+    #     behavior.apply({ "name" => "John" })
+    #   rescue SimulatedError => e
+    #     e.code  # => 500
+    #   end
+    #
+
+    class SimulateError < Base
+
+      # Apply simulate error behavior
+      #
+      # Raises SimulatedError if the behavior should be applied based
+      # on probability.
+      #
+      # @param result [Object] generated data (not modified)
+      # @param context [Generator::Context, nil] generation context (not used)
+      # @return [Object] result (if behavior not applied)
+      # @raise [SimulatedError] if behavior activates
+      #
+
+      def apply(result, context = nil)
+        if should_apply?
+          code = extract_code
+          probability = extract_probability
+          raise SimulatedError.new(code: code, probability: probability)
+        end
+        result
+      end
+
+      private
+
+
+      # Extract error code from value
+      #
+      # Extracts the HTTP status code from the behavior value configuration.
+      #
+      # @return [Integer] HTTP status code (default: 500)
+      #
+
+      def extract_code
+        case value
+        when Integer then value
+        when Hash then value[:code] || 500
+        else 500
+        end
+      end
+    end
+  end
+end
+

data/lib/synthra/cli/commands/base.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Synthra
+  class CLI
+    module Commands
+      # Base class for all CLI commands
+      #
+      # Provides common functionality for command execution including
+      # option parsing, error handling, and registry management.
+      #
+      class Base
+        # Exit codes
+        EXIT_SUCCESS = 0
+        EXIT_PARSE_ERROR = 1
+        EXIT_RUNTIME_ERROR = 2
+
+        attr_reader :args, :options
+
+        # Create a new command instance
+        #
+        # @param args [Array<String>] command arguments
+        # @param options [Hash] parsed options
+        #
+        def initialize(args, options)
+          @args = args
+          @options = options
+        end
+
+        # Execute the command
+        #
+        # @return [Integer] exit code
+        #
+        def call
+          raise NotImplementedError, "#{self.class} must implement #call"
+        end
+
+        protected
+
+        # Load schemas from a directory
+        #
+        # @param registry [Registry] registry to load schemas into
+        # @param dir [String] directory path
+        # @param validate [Boolean] whether to validate on load
+        # @return [void]
+        #
+        def load_schemas_from_dir(registry, dir, validate: true)
+          dir = File.expand_path(dir)
+          raise Errno::ENOENT, "Directory not found: #{dir}" unless Dir.exist?(dir)
+
+          pattern = File.join(dir, "*.dsl")
+          files = Dir.glob(pattern)
+
+          if files.empty?
+            $stderr.puts "No .dsl files found in #{dir}"
+            return
+          end
+
+          files.each do |f|
+            file_path = File.expand_path(f)
+            raise ArgumentError, "Invalid file path: #{f}" unless file_path.start_with?(dir)
+            registry.load_file(f, validate: validate)
+          end
+        end
+
+        # Load from path (file or directory)
+        #
+        # @param registry [Registry] registry to load into
+        # @param path [String] file or directory path
+        # @param validate [Boolean] whether to validate
+        #
+        def load_path(registry, path, validate: false)
+          if File.directory?(path)
+            load_schemas_from_dir(registry, path, validate: validate)
+          else
+            registry.load_file(path, validate: validate)
+          end
+        end
+
+        # Print success message
+        #
+        # @param message [String] message to print
+        #
+        def success(message)
+          puts "✓ #{message}"
+        end
+
+        # Print error message
+        #
+        # @param message [String] message to print
+        #
+        def error(message)
+          $stderr.puts "✗ #{message}"
+        end
+
+        # Print info message
+        #
+        # @param message [String] message to print
+        #
+        def info(message)
+          puts message
+        end
+      end
+    end
+  end
+end