synthra 0.1.0

data/lib/synthra/generator/modes.rb

@@ -0,0 +1,444 @@
+# frozen_string_literal: true
+
+module Synthra
+  module Generator
+
+    # Generation modes for different types of fake data
+    module Modes
+
+      # Curated edge case strings
+
+      EDGE_STRINGS = [
+        "",                           # empty
+        " ",                          # single space
+        "   ",                        # multiple spaces
+        "\t\n\r",                     # whitespace chars
+        "🎉💀🔥👻",                    # emojis
+        "مرحبا",                       # RTL Arabic
+        "日本語",                       # Japanese
+        "SELECT * FROM users;",       # SQL injection attempt
+        '{"key": "value"}',           # JSON in string
+        "<script>alert(1)</script>",  # XSS attempt
+        "a" * 1000,                   # very long
+        "NULL",                       # string null
+        "undefined",                  # string undefined
+        "true",                       # string boolean
+        "123",                        # string number
+        "\x00\x00",                   # null bytes
+        "O'Brien",                    # apostrophe
+        "a\nb\nc"                     # newlines
+      ].freeze
+
+
+      # Curated edge case numbers
+
+      EDGE_NUMBERS = [
+        0,
+        -1,
+        1,
+        -2_147_483_648,               # INT_MIN
+        2_147_483_647,                # INT_MAX
+        9_223_372_036_854_775_807,    # BIGINT_MAX
+        Float::MIN,
+        Float::MAX
+      ].freeze
+
+
+      # Curated edge case dates
+
+      EDGE_DATES = [
+        Date.new(1970, 1, 1),         # Unix epoch
+        Date.new(2000, 2, 29),        # Leap day
+        Date.new(2038, 1, 19),        # Y2038
+        Date.new(2020, 1, 1),         # Fixed date for determinism (replaces Date.today)
+        Date.new(1, 1, 1),            # Very old
+        Date.new(9999, 12, 31)        # Far future
+      ].freeze
+
+
+      # Base mode class
+      #
+      # Abstract base class for all generation modes. Each mode implements
+      # the #generate method to produce values in its specific style.
+      #
+      # @abstract Subclass and implement {#generate}
+      #
+
+      class BaseMode
+
+        # Create a new mode instance
+        #
+        # @param rng [Generator::RNG] random number generator
+        #
+
+        def initialize(rng)
+          @rng = rng
+        end
+
+
+        # Generate a value using this mode
+        #
+        # @abstract Must be implemented by subclasses
+        # @param _type [Base] type generator instance
+        # @param _args [Hash] type arguments
+        # @return [Object] generated value
+        # @raise [NotImplementedError] if not overridden
+        #
+
+        def generate(_type, _args)
+          raise NotImplementedError
+        end
+      end
+
+
+      # Random mode - standard Faker-based generation
+      #
+      # Generates realistic fake data using Faker library. This is the
+      # default mode for normal data generation.
+      #
+
+      class RandomMode < BaseMode
+
+        # Generate a random value
+        #
+        # @param type_instance [Base] type generator instance
+        # @param args [Hash] type arguments
+        # @return [Object] generated value
+        #
+
+        def generate(type_instance, args, context = nil)
+          context ||= Generator::Context.new
+          type_instance.generate_random(@rng, context, args)
+        end
+      end
+
+
+      # Edge mode - curated edge cases
+      #
+      # Generates edge case values (empty strings, boundary values, nulls)
+      # useful for testing boundary conditions and error handling.
+      #
+
+      class EdgeMode < BaseMode
+
+        # Generate an edge case value
+        #
+        # @param type_instance [Base] type generator instance
+        # @param args [Hash] type arguments
+        # @return [Object] edge case value
+        #
+
+        def generate(type_instance, args, context = nil)
+          context ||= Generator::Context.new
+          type_instance.generate_edge(@rng, context, args)
+        end
+
+
+        # Get an edge case string
+        #
+        # Returns a curated edge case string from EDGE_STRINGS.
+        #
+        # @return [String] edge case string
+        #
+
+        def edge_string
+          EDGE_STRINGS.sample(random: @rng.instance_variable_get(:@random))
+        end
+
+
+        # Get an edge case number
+        #
+        # Returns a curated edge case number from EDGE_NUMBERS, optionally
+        # filtered by range.
+        #
+        # @param range [Range, nil] optional range to filter candidates
+        # @return [Numeric] edge case number
+        #
+
+        def edge_number(range = nil)
+          candidates = EDGE_NUMBERS
+          if range
+            candidates = candidates.select { |n| range.cover?(n) }
+          end
+          candidates.empty? ? 0 : candidates.sample(random: @rng.instance_variable_get(:@random))
+        end
+
+
+        # Get an edge case date
+        #
+        # Returns a curated edge case date from EDGE_DATES.
+        #
+        # @return [Date] edge case date
+        #
+
+        def edge_date
+          EDGE_DATES.sample(random: @rng.instance_variable_get(:@random))
+        end
+      end
+
+
+      # Invalid mode - intentionally wrong data
+      #
+      # Generates intentionally invalid values (wrong types, malformed data)
+      # useful for testing validation logic.
+      #
+
+      class InvalidMode < BaseMode
+
+        # Generate an invalid value
+        #
+        # @param type_instance [Base] type generator instance
+        # @param args [Hash] type arguments
+        # @return [Object] invalid value
+        #
+
+        def generate(type_instance, args, context = nil)
+          context ||= Generator::Context.new
+          type_instance.generate_invalid(@rng, context, args)
+        end
+
+
+        # Get an invalid string value
+        #
+        # Returns a value that is not a valid string.
+        #
+        # @return [Object] invalid value (nil, number, array, hash, boolean)
+        #
+
+        def invalid_string
+          @rng.sample([nil, 123, [], {}, true])
+        end
+
+
+        # Get an invalid number value
+        #
+        # Returns a value that is not a valid number.
+        #
+        # @return [Object] invalid value (string, nil, array)
+        #
+
+        def invalid_number
+          @rng.sample(["not a number", nil, "NaN", "Infinity", "", []])
+        end
+
+
+        # Get an invalid email value
+        #
+        # Returns a value that is not a valid email address.
+        #
+        # @return [Object] invalid value (malformed email, nil, number)
+        #
+
+        def invalid_email
+          @rng.sample([
+            "notanemail",
+            "@missing.local",
+            "missing@",
+            "double@@at.com",
+            "spaces in@email.com",
+            nil,
+            123
+          ])
+        end
+
+
+        # Get an invalid UUID value
+        #
+        # Returns a value that is not a valid UUID.
+        #
+        # @return [Object] invalid value (string, nil, number)
+        #
+
+        def invalid_uuid
+          @rng.sample([
+            "not-a-uuid",
+            "12345",
+            "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+            nil,
+            123
+          ])
+        end
+      end
+
+
+      # Mixed mode - combination of random, edge, and invalid
+      #
+      # Probabilistically mixes all three modes according to specified ratios.
+      # Default: 80% random, 15% edge, 5% invalid.
+      #
+
+      class MixedMode < BaseMode
+
+        # Default mode ratios
+        # @return [Hash] ratio percentages
+        DEFAULT_RATIOS = {
+          random: 80,
+          edge: 15,
+          invalid: 5
+        }.freeze
+
+
+        # Create a new MixedMode instance
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param ratios [Hash] mode ratios (default: DEFAULT_RATIOS)
+        #
+
+        def initialize(rng, ratios: DEFAULT_RATIOS)
+          super(rng)
+          @ratios = ratios
+          @random_mode = RandomMode.new(rng)
+          @edge_mode = EdgeMode.new(rng)
+          @invalid_mode = InvalidMode.new(rng)
+        end
+
+
+        # Generate a value using mixed mode
+        #
+        # Selects a mode probabilistically based on ratios and generates
+        # a value using that mode.
+        #
+        # @param type_instance [Base] type generator instance
+        # @param args [Hash] type arguments
+        # @return [Object] generated value
+        #
+
+        def generate(type_instance, args, context = nil)
+          context ||= Generator::Context.new
+          roll = @rng.rand(100)
+          cumulative = 0
+
+          if roll < (cumulative += @ratios[:random])
+            @random_mode.generate(type_instance, args, context)
+          elsif roll < (cumulative += @ratios[:edge])
+            @edge_mode.generate(type_instance, args, context)
+          else
+            @invalid_mode.generate(type_instance, args, context)
+          end
+        end
+      end
+
+
+      # Hostile mode - security attack payloads
+      #
+      # Generates security attack payloads (SQL injection, XSS, buffer overflow)
+      # for security testing of API endpoints consuming this data.
+      #
+      class HostileMode < BaseMode
+        # Security attack payloads
+        SQL_INJECTION_PAYLOADS = [
+          "' OR '1'='1",
+          "'; DROP TABLE users;--",
+          "' UNION SELECT * FROM users--",
+          "1' OR '1'='1",
+          "admin'--",
+          "' OR 1=1;--",
+          "1' AND '1'='1",
+          "' OR 'x'='x",
+          "') OR ('1'='1--",
+          "1' OR '1'='1' /*"
+        ].freeze
+
+        XSS_PAYLOADS = [
+          "<script>alert(1)</script>",
+          "<img src=x onerror=alert(1)>",
+          "<svg onload=alert(1)>",
+          "javascript:alert(1)",
+          "<body onload=alert(1)>",
+          "<iframe src=javascript:alert(1)>",
+          "<input onfocus=alert(1) autofocus>",
+          "<select onfocus=alert(1) autofocus>",
+          "<textarea onfocus=alert(1) autofocus>",
+          "<keygen onfocus=alert(1) autofocus>"
+        ].freeze
+
+        BUFFER_OVERFLOW_PAYLOADS = [
+          "A" * 1000,
+          "A" * 10000,
+          "A" * 100000,
+          "\x00" * 1000,
+          "\xFF" * 1000
+        ].freeze
+
+        UNICODE_ATTACKS = [
+          "\u202E" + "evil" + "\u202D", # RTL override
+          "\uFEFF" + "text", # BOM
+          "\u200B" * 100, # Zero-width spaces
+          "\u2060" * 100, # Word joiner
+          "Zalgo: H\u0301\u0302\u0303\u0304\u0305\u0306\u0307\u0308\u0309\u030A\u030B\u030C\u030D\u030E\u030F\u0310\u0311\u0312\u0313\u0314\u0315\u0316\u0317\u0318\u0319\u031A\u031B\u031C\u031D\u031E\u031F\u0320\u0321\u0322\u0323\u0324\u0325\u0326\u0327\u0328\u0329\u032A\u032B\u032C\u032D\u032E\u032F\u0330\u0331\u0332\u0333\u0334\u0335\u0336\u0337\u0338\u0339\u033A\u033B\u033C\u033D\u033E\u033F\u0340\u0341\u0342\u0343\u0344\u0345\u0346\u0347\u0348\u0349\u034A\u034B\u034C\u034D\u034E\u034F\u0350\u0351\u0352\u0353\u0354\u0355\u0356\u0357\u0358\u0359\u035A\u035B\u035C\u035D\u035E\u035F\u0360\u0361\u0362\u0363\u0364\u0365\u0366\u0367\u0368\u0369\u036A\u036B\u036C\u036D\u036E\u036F\u0489\u048A\u048B\u048C\u048D\u048E\u048F\u0490\u0491\u0492\u0493\u0494\u0495\u0496\u0497\u0498\u0499\u049A\u049B\u049C\u049D\u049E\u049F\u04A0\u04A1\u04A2\u04A3\u04A4\u04A5\u04A6\u04A7\u04A8\u04A9\u04AA\u04AB\u04AC\u04AD\u04AE\u04AF\u04B0\u04B1\u04B2\u04B3\u04B4\u04B5\u04B6\u04B7\u04B8\u04B9\u04BA\u04BB\u04BC\u04BD\u04BE\u04BF\u04C0\u04C1\u04C2\u04C3\u04C4\u04C5\u04C6\u04C7\u04C8\u04C9\u04CA\u04CB\u04CC\u04CD\u04CE\u04CF\u04D0\u04D1\u04D2\u04D3\u04D4\u04D5\u04D6\u04D7\u04D8\u04D9\u04DA\u04DB\u04DC\u04DD\u04DE\u04DF\u04E0\u04E1\u04E2\u04E3\u04E4\u04E5\u04E6\u04E7\u04E8\u04E9\u04EA\u04EB\u04EC\u04ED\u04EE\u04EF\u04F0\u04F1\u04F2\u04F3\u04F4\u04F5\u04F6\u04F7\u04F8\u04F9\u04FA\u04FB\u04FC\u04FD\u04FE\u04FF"
+        ].freeze
+
+        # Generate a hostile value
+        #
+        # @param type_instance [Base] type generator instance
+        # @param args [Hash] type arguments
+        # @return [Object] hostile value
+        #
+        def generate(type_instance, args, context = nil)
+          context ||= Generator::Context.new
+          type_instance.generate_hostile(@rng, context, args)
+        end
+
+        # Get SQL injection payload
+        #
+        # @return [String] SQL injection string
+        #
+        def sql_injection
+          SQL_INJECTION_PAYLOADS.sample(random: @rng.instance_variable_get(:@random))
+        end
+
+        # Get XSS payload
+        #
+        # @return [String] XSS attack string
+        #
+        def xss_payload
+          XSS_PAYLOADS.sample(random: @rng.instance_variable_get(:@random))
+        end
+
+        # Get buffer overflow payload
+        #
+        # @return [String] buffer overflow string
+        #
+        def buffer_overflow
+          BUFFER_OVERFLOW_PAYLOADS.sample(random: @rng.instance_variable_get(:@random))
+        end
+
+        # Get Unicode attack payload
+        #
+        # @return [String] Unicode attack string
+        #
+        def unicode_attack
+          UNICODE_ATTACKS.sample(random: @rng.instance_variable_get(:@random))
+        end
+      end
+
+
+      # Factory method to create mode instance
+      #
+      # Creates an appropriate mode instance based on the mode symbol.
+      #
+      # @param mode [Symbol] mode name (:random, :edge, :invalid, :mixed)
+      # @param rng [Generator::RNG] random number generator
+      # @return [BaseMode] mode instance
+      # @raise [ArgumentError] if mode is unknown
+      #
+      # @example
+      #   Modes.create(:edge, rng)
+      #   # => #<EdgeMode>
+      #
+
+      def self.create(mode, rng)
+        case mode
+        when :random then RandomMode.new(rng)
+        when :edge then EdgeMode.new(rng)
+        when :invalid then InvalidMode.new(rng)
+        when :hostile then HostileMode.new(rng)
+        when :mixed then MixedMode.new(rng)
+        else
+          raise ArgumentError, "Unknown mode: #{mode}"
+        end
+      end
+    end
+  end
+end
+

data/lib/synthra/generator/resolver.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+module Synthra
+  module Generator
+
+    # Resolves cross-schema references
+    class Resolver
+      def initialize(registry)
+        @registry = registry
+        @cache = {}
+        @generating = Set.new
+        @mutex = Mutex.new
+      end
+
+
+      # Resolve a reference to another schema's field
+      #
+      # @param schema_name [String] the schema name
+      # @param field_path [String] dot-separated field path
+      # @param depth [Integer] current recursion depth (default: 0)
+      # @param seed [Integer, nil] deterministic seed for the referenced schema's generation
+      #   (derived from the parent RNG by the Reference type) — makes ref() values reproducible
+      # @return [Object] the resolved value
+      # @raise [RecursionLimitError] if recursion depth exceeds configured limit
+
+      def resolve(schema_name, field_path, depth: 0, seed: nil)
+
+        # Validate recursion depth against configured limits (before mutex to avoid deadlock)
+        # Check depth + 1 because we're about to generate at that depth
+        Synthra.configuration.limits.validate_recursion!(depth + 1)
+
+
+        # Check cache first (thread-safe read)
+        cache_key = "#{schema_name}.#{field_path}"
+        @mutex.synchronize do
+          return @cache[cache_key] if @cache.key?(cache_key)
+        end
+
+
+        # Check for cycles BEFORE acquiring mutex to avoid deadlock on recursive calls
+        @mutex.synchronize do
+          if @generating.include?(schema_name)
+            cycle = @generating.to_a + [schema_name]
+            raise CyclicReferenceError, cycle
+          end
+        end
+
+
+        # Generate the referenced schema (outside mutex to allow recursive calls)
+        begin
+          @mutex.synchronize do
+            @generating.add(schema_name)
+          end
+
+          schema = @registry.schema(schema_name)
+
+          # Pass this resolver instance to ensure cycle detection works
+          # The Engine will reuse this resolver instead of creating a new one.
+          # `seed` (from the parent RNG) makes the referenced record reproducible by seed.
+          record = schema.generate(seed: seed, registry: @registry, depth: depth + 1, resolver: self)
+
+
+          # Cache all fields from this schema
+          @mutex.synchronize do
+            record.each do |key, val|
+              @cache["#{schema_name}.#{key}"] = val
+            end
+
+
+            # Extract the specific field
+            value = extract_path(record, field_path)
+            @cache[cache_key] = value
+            value
+          end
+        rescue KeyError
+          raise MissingReferenceError.new(schema_name: schema_name, field_path: field_path)
+        ensure
+          @mutex.synchronize do
+            @generating.delete(schema_name)
+          end
+        end
+      end
+
+
+      # Get schemas in dependency order
+      #
+      # @return [Array<String>] schema names ordered by dependencies
+
+      def dependency_order
+        dependencies = build_dependency_graph
+        topological_sort(dependencies)
+      end
+
+
+      # Detect cycles in schema references
+      #
+      # @return [Array<Array<String>>] array of cycle paths
+
+      def detect_cycles
+        cycles = []
+        visited = Set.new
+        stack = []
+
+        @registry.names.each do |name|
+          detect_cycles_from(name, visited, stack, cycles)
+        end
+
+        cycles
+      end
+
+
+      # Clear the resolution cache
+      #
+      # @return [void]
+
+      def clear_cache
+        @mutex.synchronize do
+          @cache.clear
+          @generating.clear
+        end
+      end
+
+      private
+
+
+      # Extract value from record using dot-separated path
+      #
+      # Traverses nested hashes using dot notation (e.g., "address.city").
+      #
+      # @param record [Hash] record to extract from
+      # @param path [String] dot-separated field path
+      # @return [Object, nil] extracted value or nil if not found
+      #
+
+      def extract_path(record, path)
+        parts = path.to_s.split(".")
+        value = record
+
+        parts.each do |part|
+          case value
+          when Hash
+            value = value[part] || value[part.to_sym]
+          else
+            return nil
+          end
+          return nil if value.nil?
+        end
+
+        value
+      end
+
+
+      # Build dependency graph from schema references
+      #
+      # Analyzes all schemas to build a graph of cross-schema dependencies.
+      #
+      # @return [Hash] dependency graph { schema_name => [dependent_schemas] }
+      #
+
+      def build_dependency_graph
+        graph = Hash.new { |h, k| h[k] = [] }
+
+        @registry.each do |name, schema|
+          schema.fields.each do |field|
+            if field.type_name == "reference"
+              ref = field.type_args[:ref]
+              ref_schema = ref.respond_to?(:schema_name) ? ref.schema_name : ref&.dig(:schema_name)
+              graph[name] << ref_schema if ref_schema
+            end
+          end
+        end
+
+        graph
+      end
+
+
+      # Topologically sort schemas by dependencies
+      #
+      # Orders schemas so that dependencies come before dependents.
+      # Uses Kahn's algorithm for topological sorting.
+      #
+      # @param graph [Hash] dependency graph
+      # @return [Array<String>] sorted schema names
+      #
+
+      def topological_sort(graph)
+        in_degree = Hash.new(0)
+        all_nodes = Set.new(@registry.names)
+
+        graph.each do |node, deps|
+          deps.each { |dep| in_degree[dep] += 1 }
+        end
+
+        queue = all_nodes.select { |n| in_degree[n].zero? }
+        result = []
+
+        until queue.empty?
+          node = queue.shift
+          result << node
+
+          graph[node].each do |dep|
+            in_degree[dep] -= 1
+            queue << dep if in_degree[dep].zero?
+          end
+        end
+
+
+        # If we couldn't sort all, there's a cycle - just return all names
+        result.length == all_nodes.length ? result : @registry.names
+      end
+
+
+      # Detect cycles starting from a node
+      #
+      # Recursively traverses the dependency graph to detect cycles.
+      # Uses depth-first search with cycle detection.
+      #
+      # @param node [String] schema name to start from
+      # @param visited [Set] set of visited nodes
+      # @param stack [Array] current path stack
+      # @param cycles [Array] array to collect detected cycles
+      # @return [void]
+      #
+
+      def detect_cycles_from(node, visited, stack, cycles)
+        return if visited.include?(node)
+
+        if stack.include?(node)
+          cycle_start = stack.index(node)
+          cycles << stack[cycle_start..] + [node]
+          return
+        end
+
+        stack.push(node)
+
+        begin
+          schema = @registry.schema(node)
+          schema.fields.each do |field|
+            if field.type_name == "reference"
+              ref = field.type_args[:ref]
+              ref_schema = ref.respond_to?(:schema_name) ? ref.schema_name : ref&.dig(:schema_name)
+              detect_cycles_from(ref_schema, visited, stack, cycles) if ref_schema
+            end
+          end
+        rescue KeyError
+
+          # Schema not found
+        end
+
+        stack.pop
+        visited.add(node)
+      end
+    end
+  end
+end
+