synthra 0.1.0

data/lib/synthra/personas.rb

@@ -0,0 +1,397 @@
+# frozen_string_literal: true
+
+module Synthra
+  # Personas: Named Data Profiles
+  #
+  # Define reusable data profiles that represent different user types,
+  # test cases, or data states. More semantic than "modes" - think
+  # in terms of WHO you're generating data for.
+  #
+  # @example Define personas
+  #   Synthra::Personas.define(:happy_path) do
+  #     mode :random
+  #     override User, email_verified: true, subscription: "premium"
+  #   end
+  #
+  #   Synthra::Personas.define(:edge_case_user) do
+  #     mode :edge
+  #     override User, name: "X", email: "a@b.co"
+  #   end
+  #
+  # @example Use personas
+  #   Synthra.as(:happy_path) { User.generate }
+  #   Synthra.as(:edge_case_user) { User.generate }
+  #
+  module Personas
+    class << self
+      # Registry of defined personas
+      def registry
+        @registry ||= {}
+      end
+
+      # Define a new persona
+      #
+      # @param name [Symbol] persona name
+      # @yield persona configuration block
+      # @return [Persona] the defined persona
+      #
+      def define(name, &block)
+        persona = Persona.new(name)
+        persona.instance_eval(&block) if block
+        registry[name] = persona
+        persona
+      end
+
+      # Get a persona by name
+      #
+      # @param name [Symbol] persona name
+      # @return [Persona, nil]
+      #
+      def [](name)
+        registry[name]
+      end
+
+      # List all personas
+      #
+      # @return [Array<Symbol>]
+      #
+      def list
+        registry.keys
+      end
+
+      # Generate data using a persona
+      #
+      # @param persona_name [Symbol] persona to use
+      # @yield block for generation
+      # @return [Object] result of the block
+      #
+      def as(persona_name, &block)
+        persona = registry[persona_name]
+        raise ArgumentError, "Unknown persona: #{persona_name}" unless persona
+
+        persona.apply(&block)
+      end
+
+      # Load personas from configuration
+      #
+      # @param config [Hash] configuration hash
+      #
+      def load_config(config)
+        config.each do |name, definition|
+          define(name.to_sym) do
+            # :nocov: the `&.` nil-arm is unreachable — the trailing `if definition["mode"]` guard
+            # already guarantees definition["mode"] is truthy whenever this line runs.
+            mode definition["mode"]&.to_sym if definition["mode"]
+            # :nocov:
+            seed definition["seed"] if definition["seed"]
+
+            definition["overrides"]&.each do |schema, overrides|
+              override schema, **Personas.send(:symbolize_keys, overrides)
+            end
+
+            definition["traits"]&.each do |trait|
+              include_trait trait.to_sym
+            end
+          end
+        end
+      end
+
+      # Load personas from YAML file
+      #
+      # @param path [String] path to YAML file
+      #
+      def load_file(path)
+        require "yaml"
+        config = YAML.safe_load(File.read(path), permitted_classes: [Symbol])
+        load_config(config["personas"] || config)
+      end
+
+      # Reset all personas (clears custom personas, preserves built-ins)
+      def reset!
+        @registry = {}
+        define_built_in_personas!
+      end
+
+      # Define built-in personas
+      def define_built_in_personas!
+        define(:default) do
+          mode :random
+        end
+
+        define(:happy_path) do
+          mode :random
+          # Most common, valid data
+        end
+
+        define(:edge_cases) do
+          mode :edge
+          # Boundary values, empty strings, max lengths
+        end
+
+        define(:invalid) do
+          mode :invalid
+          # Invalid data for validation testing
+        end
+
+        define(:security_test) do
+          mode :hostile
+          # SQL injection, XSS, malicious payloads
+        end
+
+        define(:stress_test) do
+          mode :edge
+          transform do |data, _context|
+            # Make strings very long
+            data.transform_values do |v|
+              v.is_a?(String) ? v * 100 : v
+            end
+          end
+        end
+      end
+
+      private
+
+      def symbolize_keys(hash)
+        hash.transform_keys(&:to_sym)
+      end
+    end
+
+    # A persona definition
+    class Persona
+      attr_reader :name, :generation_mode, :generation_seed
+      attr_reader :overrides, :traits, :transforms
+
+      def initialize(name)
+        @name = name
+        @generation_mode = :random
+        @generation_seed = nil
+        @overrides = {}
+        @traits = []
+        @transforms = []
+        @before_hooks = []
+        @after_hooks = []
+      end
+
+      # Set generation mode
+      #
+      # @param mode_name [Symbol] :random, :edge, :invalid, :hostile, :mixed
+      #
+      def mode(mode_name)
+        @generation_mode = mode_name
+      end
+
+      # Set random seed
+      #
+      # @param value [Integer] seed value
+      #
+      def seed(value)
+        @generation_seed = value
+      end
+
+      # Add overrides for a schema
+      #
+      # @param schema [String, Symbol, Class] schema name or class
+      # @param fields [Hash] field overrides
+      #
+      def override(schema, **fields)
+        schema_name = normalize_schema_name(schema)
+        @overrides[schema_name] ||= {}
+        @overrides[schema_name].merge!(fields)
+      end
+
+      # Include a trait
+      #
+      # @param trait_name [Symbol] trait to include
+      #
+      def include_trait(trait_name)
+        @traits << trait_name
+      end
+
+      # Add a transform function
+      #
+      # @param schema [String, Symbol] schema name (nil for all)
+      # @yield [data, context] transform block
+      #
+      def transform(schema = nil, &block)
+        @transforms << { schema: schema&.to_s, block: block }
+      end
+
+      # Add before hook
+      def before(&block)
+        @before_hooks << block
+      end
+
+      # Add after hook
+      def after(&block)
+        @after_hooks << block
+      end
+
+      # Apply this persona and execute block
+      #
+      # @yield block for generation
+      # @return [Object] result of the block
+      #
+      def apply(&block)
+        context = PersonaContext.new(self)
+        context.apply(&block)
+      end
+
+      # Get effective overrides for a schema
+      #
+      # @param schema_name [String] schema name
+      # @return [Hash] merged overrides
+      #
+      def overrides_for(schema_name)
+        result = {}
+
+        # Apply trait overrides first
+        @traits.each do |trait_name|
+          trait = Traits[trait_name]
+          result.merge!(trait.overrides_for(schema_name)) if trait
+        end
+
+        # Apply persona overrides
+        result.merge!(@overrides[schema_name] || {})
+
+        result
+      end
+
+      private
+
+      def normalize_schema_name(schema)
+        case schema
+        when String then schema
+        when Symbol then schema.to_s
+        when Class then schema.name
+        else schema.to_s
+        end
+      end
+    end
+
+    # Runtime context for persona application
+    class PersonaContext
+      attr_reader :persona
+
+      def initialize(persona)
+        @persona = persona
+        @generated = {}
+      end
+
+      def apply(&block)
+        # Run before hooks
+        @persona.instance_variable_get(:@before_hooks).each { |h| instance_exec(&h) }
+
+        # Set thread-local context
+        old_context = Thread.current[:synthra_persona]
+        Thread.current[:synthra_persona] = self
+
+        # Yield self to the block instead of instance_eval to preserve caller's context
+        result = block.call(self)
+
+        # Run after hooks
+        @persona.instance_variable_get(:@after_hooks).each { |h| instance_exec(&h) }
+
+        result
+      ensure
+        Thread.current[:synthra_persona] = old_context
+      end
+
+      # Generate data with persona settings
+      def generate(schema_name, **options)
+        schema = Synthra.registry.schema(schema_name.to_s)
+
+        merged_options = {
+          mode: @persona.generation_mode,
+          seed: @persona.generation_seed,
+          overrides: @persona.overrides_for(schema_name.to_s)
+        }.merge(options)
+
+        data = schema.generate(**merged_options)
+
+        # Apply transforms
+        @persona.transforms.each do |transform|
+          if transform[:schema].nil? || transform[:schema] == schema_name.to_s
+            data = transform[:block].call(data, self)
+          end
+        end
+
+        @generated[schema_name.to_s] = data
+        data
+      end
+    end
+  end
+
+  # Reusable traits for personas
+  module Traits
+    class << self
+      def registry
+        @registry ||= {}
+      end
+
+      # Define a trait
+      #
+      # @param name [Symbol] trait name
+      # @yield trait configuration
+      #
+      def define(name, &block)
+        trait = Trait.new(name)
+        trait.instance_eval(&block) if block
+        registry[name] = trait
+      end
+
+      def [](name)
+        registry[name]
+      end
+
+      def reset!
+        @registry = {}
+      end
+    end
+
+    class Trait
+      attr_reader :name, :overrides
+
+      def initialize(name)
+        @name = name
+        @overrides = {}
+      end
+
+      def override(schema, **fields)
+        schema_name = schema.to_s
+        @overrides[schema_name] ||= {}
+        @overrides[schema_name].merge!(fields)
+      end
+
+      def overrides_for(schema_name)
+        @overrides[schema_name] || {}
+      end
+    end
+  end
+
+  # Extend main module with persona support
+  class << self
+    # Generate data using a persona
+    #
+    # @param persona_name [Symbol] persona to use
+    # @yield block for generation
+    # @return [Object] result
+    #
+    # @example
+    #   Synthra.as(:happy_path) { generate("User") }
+    #
+    def as(persona_name, &block)
+      Personas.as(persona_name, &block)
+    end
+
+    # Get current persona context
+    #
+    # @return [Personas::PersonaContext, nil]
+    #
+    def current_persona
+      Thread.current[:synthra_persona]
+    end
+  end
+
+  # Initialize built-in personas
+  Personas.define_built_in_personas!
+end

data/lib/synthra/property_testing.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+# =============================================================================
+# Synthra Property-Based Testing Integration
+# =============================================================================
+#
+# Provides RSpec helpers for property-based testing with Synthra schemas.
+# Allows you to verify properties hold for all generated data.
+#
+# @example Basic property test
+#   RSpec.describe "User Registration" do
+#     include Synthra::PropertyTesting
+#
+#     it "accepts all valid users" do
+#       verify_property("User") do |user_data|
+#         user = User.create(user_data)
+#         expect(user).to be_valid
+#         expect(user.save).to be_truthy
+#       end
+#     end
+#   end
+#
+# @example With custom count and seed
+#   verify_property("Order", count: 1000, seed: 42) do |order_data|
+#     expect(order_data["total"]).to be >= 0
+#   end
+#
+# =============================================================================
+
+module Synthra
+  module PropertyTesting
+    # Verify a property holds for generated data
+    #
+    # Generates multiple records from a schema and verifies a property
+    # holds for all of them. Raises if property fails for any record.
+    #
+    # @param schema_name [String] schema name to generate from
+    # @param count [Integer] number of records to generate (default: 100)
+    # @param seed [Integer, nil] random seed for reproducibility
+    # @param mode [Symbol] generation mode (default: :random)
+    # @param registry [Registry, nil] registry for schema lookup
+    # @yield [Hash] block to verify property
+    # @yieldparam record [Hash] generated record
+    # @raise [RSpec::Expectations::ExpectationNotMetError] if property fails
+    #
+    # @example
+    #   verify_property("User") do |user|
+    #     expect(user["email"]).to match(/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
+    #   end
+    #
+    def verify_property(schema_name, count: 100, seed: nil, mode: :random, registry: nil)
+      registry ||= Registry.new
+      schema = registry.schema(schema_name)
+
+      records = schema.generate_many(count, seed: seed, mode: mode, registry: registry)
+
+      records.each_with_index do |record, idx|
+        begin
+          yield(record)
+        rescue RSpec::Expectations::ExpectationNotMetError => e
+          raise RSpec::Expectations::ExpectationNotMetError,
+                "Property failed for record #{idx + 1}/#{count} (seed: #{seed || 'random'}):\n" \
+                "#{e.message}\n" \
+                "Record: #{record.inspect}"
+        end
+      end
+    end
+
+    # Verify a property holds for a stream of generated data
+    #
+    # Generates records lazily and verifies property for each.
+    # More memory-efficient for large counts.
+    #
+    # @param schema_name [String] schema name to generate from
+    # @param count [Integer] number of records to generate
+    # @param seed [Integer, nil] random seed
+    # @param mode [Symbol] generation mode
+    # @param registry [Registry, nil] registry for schema lookup
+    # @yield [Hash] block to verify property
+    #
+    # @example
+    #   verify_property_stream("Order", count: 10000) do |order|
+    #     expect(order["items"]).to be_an(Array)
+    #   end
+    #
+    def verify_property_stream(schema_name, count: 1000, seed: nil, mode: :random, registry: nil)
+      registry ||= Registry.new
+      schema = registry.schema(schema_name)
+
+      stream = schema.generate_many_stream(count, seed: seed, mode: mode, registry: registry)
+
+      stream.each_with_index do |record, idx|
+        begin
+          yield(record)
+        rescue RSpec::Expectations::ExpectationNotMetError => e
+          raise RSpec::Expectations::ExpectationNotMetError,
+                "Property failed for record #{idx + 1}/#{count} (seed: #{seed || 'random'}):\n" \
+                "#{e.message}\n" \
+                "Record: #{record.inspect}"
+        end
+      end
+    end
+
+    # Shrink a failing test case to find minimal counterexample
+    #
+    # When a property fails, attempts to shrink the failing record
+    # to find a smaller counterexample.
+    #
+    # @param schema_name [String] schema name
+    # @param failing_record [Hash] record that caused failure
+    # @param registry [Registry, nil] registry
+    # @yield [Hash] block to verify property
+    # @return [Hash] minimal counterexample
+    #
+    def shrink_counterexample(schema_name, failing_record, registry: nil, &block)
+      registry ||= Registry.new
+      schema = registry.schema(schema_name)
+
+      current = failing_record.dup
+      improved = true
+
+      while improved
+        improved = false
+
+        # Try removing optional fields
+        current.keys.each do |key|
+          next unless schema.field(key)&.optional?
+
+          candidate = current.dup
+          candidate.delete(key)
+
+          begin
+            block.call(candidate)
+          rescue RSpec::Expectations::ExpectationNotMetError
+            # Still fails with smaller record
+            current = candidate
+            improved = true
+            break
+          end
+        end
+
+        # Try simplifying array values
+        current.each do |key, value|
+          next unless value.is_a?(Array) && value.length > 1
+
+          candidate = current.dup
+          candidate[key] = value[0..0] # Single element
+
+          begin
+            block.call(candidate)
+          rescue RSpec::Expectations::ExpectationNotMetError
+            current = candidate
+            improved = true
+            break
+          end
+        end
+      end
+
+      current
+    end
+  end
+end
+
+# Include in RSpec
+# :nocov: — load-time RSpec wiring. This file is only required while RSpec is
+# loaded, so `defined?(RSpec)` is always truthy here; the false arm is unreachable.
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.include Synthra::PropertyTesting
+  end
+end
+# :nocov: