synthra 0.1.0

data/lib/synthra/types/core/primitives.rb

@@ -0,0 +1,586 @@
+# frozen_string_literal: true
+
+module Synthra
+  module Types
+    module Core
+      # Text type generator with locale support
+      #
+      # Generates random text strings with optional length constraints and locale support.
+      # Uses Faker for locale-specific text generation when available.
+      #
+      # @example Basic usage
+      #   text(50..100)  # 50-100 characters
+      #   text(100)      # Exactly 100 characters
+      #   text(min: 50, max: 200)  # Named arguments
+      #
+      # @example With locale
+      #   text(ar)                # Arabic text (default length)
+      #   text(50, language: :ar)  # Arabic text, ~50 chars
+      #   text(locale: :es)       # Spanish text
+      #
+      # @example Multiple args: locale + length (order-independent)
+      #   text(ar, 1..10)   # Arabic text, 1-10 characters
+      #   text(1..10, ar)   # Same: 1-10 chars, Arabic
+      #   text(en, 5..50)   # English text, 5-50 characters
+      #
+      class Text < Base
+        # Generate random text
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @option args [Integer] :min minimum length
+        # @option args [Integer] :max maximum length
+        # @option args [Range] :range length range
+        # @option args [Hash] :range hash with :min and :max keys
+        # @option args [Symbol, String] :language locale alias (:en, :ar, :es, etc.)
+        # @option args [Symbol, String] :locale locale identifier
+        # @return [String] generated text
+        #
+        def generate_random(rng, context, args)
+          # Check for locale in various argument formats:
+          # 1. Explicit: text(locale: :ar), text(language: :ar), text(lang: :ar)
+          # 2. Shorthand: text(ar) - parser should store this as args[:locale] since Synthra 1.x
+          # 3. Fallback: text(ar) - older versions stored as args[:value]
+          # An Integer or Range :value is a LENGTH (e.g. text(50), text(50..200)), not a locale,
+          # so it must not be fed to normalize_locale (Integer#to_sym would raise NoMethodError).
+          locale_arg = args[:value]
+          locale_arg = nil if locale_arg.is_a?(Integer) || locale_arg.is_a?(Range)
+          locale_value = args[:locale] || args[:language] || args[:lang] || locale_arg
+          locale = normalize_locale(locale_value)
+          
+          # Prefer readable sentences/words over random character strings
+          generate_readable_text(rng, context, args, locale)
+        end
+
+        # Generate edge case text
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [String] edge case text
+        #
+        def generate_edge(rng, context, args)
+          rng.sample(Generator::Modes::EDGE_STRINGS)
+        end
+
+        # Generate invalid text values
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Object] invalid value (nil, number, etc.)
+        #
+        def generate_invalid(rng, context, args)
+          rng.sample([nil, 123, [], {}, true, false])
+        end
+
+        # Generate hostile/malicious text for security testing
+        #
+        # Returns attack vectors including SQLi, XSS, path traversal,
+        # buffer overflows, and unicode edge cases.
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [String] hostile payload
+        #
+        def generate_hostile(rng, context, args)
+          require_relative "../hostile_payloads"
+          rng.sample(HostilePayloads::ALL)
+        end
+
+        private
+
+        # Extract length constraints from arguments
+        #
+        # @param args [Hash] type arguments
+        # @return [Array<Integer>] [min_length, max_length]
+        #
+        def extract_length(args)
+          if args[:range].is_a?(Range)
+            args[:range].minmax
+          elsif args[:range].is_a?(Hash)
+            [args[:range][:min] || args[:range]["min"] || 10, args[:range][:max] || args[:range]["max"] || 100]
+          elsif args[:min] || args[:max]
+            [args[:min] || 10, args[:max] || 100]
+          elsif args[:value].is_a?(Integer)
+            [args[:value], args[:value]]
+          elsif args[:value].is_a?(Range)
+            args[:value].minmax
+          else
+            [10, 100] # Default range
+          end
+        end
+
+        # Normalize locale identifier
+        #
+        # @param locale [Symbol, String] locale identifier
+        # @return [Symbol] normalized locale
+        #
+        def normalize_locale(locale)
+          return :en if locale.nil?
+
+          locale_str = locale.to_s.downcase
+          case locale_str
+          when "en", "english" then :en
+          when "ar", "arabic" then :ar
+          when "es", "spanish" then :es
+          when "fr", "french" then :fr
+          when "de", "german" then :de
+          when "it", "italian" then :it
+          when "pt", "portuguese" then :pt
+          when "ru", "russian" then :ru
+          when "zh", "chinese" then :zh_CN
+          when "ja", "japanese" then :ja
+          when "ko", "korean" then :ko
+          when "hi", "hindi" then :hi
+          else
+            locale.to_sym
+          end
+        end
+
+        # Generate readable text (words/sentences) instead of random character strings.
+        # Respects character length when args include :range, :min/:max, or :value.
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @param locale [Symbol] locale identifier
+        # @return [String] generated readable text
+        #
+        def generate_readable_text(rng, context, args, locale)
+          min_len, max_len = extract_length(args)
+          word_count = rng.int([min_len / 8, 2].max, [max_len / 5, 25].max)
+
+          text = begin
+            with_seeded_faker(rng) do
+              with_faker_locale(locale) do
+                if english_locale?(locale)
+                  faker_english_words(word_count)
+                else
+                  faker_localized_words(word_count, locale)
+                end
+              end
+            end
+          rescue StandardError
+            with_seeded_faker(rng) do
+              with_faker_locale(locale) { Faker::Lorem.words(number: [word_count, 10].min).join(" ") }
+            end
+          # :nocov: sibling rescue cannot catch errors raised by the rescue above it (dead code)
+          rescue StandardError
+            "Sample text"
+            # :nocov:
+          end
+
+          truncate_to_length(text, rng, min_len, max_len, args)
+        end
+
+        # Seed Faker deterministically from rng so word/sentence CONTENT — not just the word
+        # COUNT — is reproducible by seed. Without this, Faker::Books::Lovecraft.words (and the
+        # other word providers below) use Faker's process-global RNG and vary across runs even
+        # for the same generation seed. Derives a fresh per-call seed from rng (which advances,
+        # so each record still differs) and restores the previous Faker::Config.random after.
+        def with_seeded_faker(rng)
+          return yield unless defined?(Faker::Config) && Faker::Config.respond_to?(:random)
+
+          previous = Faker::Config.random
+          Faker::Config.random = Random.new(rng.rand(2**31))
+          begin
+            yield
+          ensure
+            Faker::Config.random = previous
+          end
+        end
+
+        def with_faker_locale(locale)
+          return yield unless Faker::Config.respond_to?(:locale=)
+
+          original = Faker::Config.locale
+          Faker::Config.locale = locale
+          yield
+        ensure
+          Faker::Config.locale = original
+        end
+
+        def english_locale?(locale)
+          locale.to_s.downcase.start_with?("en")
+        end
+
+        # Truncate or slice text to fit within [min_len, max_len] when length was explicitly specified.
+        # Preserves locale (e.g. Arabic text stays Arabic).
+        #
+        def truncate_to_length(text, rng, min_len, max_len, args)
+          has_explicit_length = args.key?(:range) || args.key?(:min) || args.key?(:max) ||
+            (args[:value].is_a?(Integer) || args[:value].is_a?(Range))
+          return text unless has_explicit_length
+          return "" if max_len <= 0 # zero-length requested → empty string (clamp(1, 0) would raise)
+
+          target_len = rng.int(min_len.clamp(1, max_len), max_len)
+          text.length > target_len ? text[0, target_len] : text
+        end
+
+        # English words for text/string — Faker::Hipster reads as English (e.g. "artisan kale tote
+        # bag"), matching the `words` type. (Was Faker::Books::Lovecraft, which leaked horror
+        # vocabulary "stygian eldritch cyclopean tentacles" into post content, excerpts and tags.)
+        def faker_english_words(word_count)
+          word_count = word_count.clamp(1, 25)
+          Faker::Hipster.words(number: word_count).join(" ")
+        end
+
+        # Localized words via Faker (for non-English locales)
+        # Uses locale-aware Faker providers that actually generate text in the target language
+        def faker_localized_words(word_count, locale)
+          word_count = word_count.clamp(1, 25)
+          
+          # Build text from locale-aware providers
+          words = []
+          attempts = 0
+          max_attempts = word_count * 3
+          
+          while words.length < word_count && attempts < max_attempts
+            attempts += 1
+            
+            # Try various localized Faker providers
+            # :nocov: each `if defined?(Faker::X)` guard's false arm is unreachable (Faker is a hard
+            # dependency, always loaded); the case arm chosen by rand(6) is also non-deterministic.
+            text = case rand(6)
+                   when 0
+                     Faker::Name.name if defined?(Faker::Name)
+                   when 1
+                     Faker::Address.city if defined?(Faker::Address)
+                   when 2
+                     Faker::Company.name if defined?(Faker::Company)
+                   when 3
+                     Faker::Address.country if defined?(Faker::Address)
+                   when 4
+                     Faker::Address.street_name if defined?(Faker::Address)
+                   else
+                     Faker::Company.industry if defined?(Faker::Company) && Faker::Company.respond_to?(:industry)
+                   end
+            # :nocov:
+            
+            words += text.to_s.split(/\s+/) if text
+          end
+          
+          words.first(word_count).join(" ")
+        rescue StandardError
+          # Fallback to Lorem if localized providers fail
+          Faker::Lorem.words(number: word_count).join(" ")
+        end
+
+        # Generate text with locale support (character-based; used when explicit length needed)
+        #
+        def generate_text_with_locale(rng, context, length, locale)
+          adapter = faker_adapter(context)
+
+          if adapter
+            adapter.characters(number: length, locale: locale)
+
+          else
+            original_locale = Faker::Config.locale
+            begin
+              Faker::Config.locale = locale if Faker::Config.respond_to?(:locale=)
+              Faker::Lorem.characters(number: length)
+            rescue StandardError
+              generate_random_alphanumeric(rng, length)
+            ensure
+              Faker::Config.locale = original_locale if Faker::Config.respond_to?(:locale=)
+            end
+          end
+        rescue StandardError
+          generate_random_alphanumeric(rng, length)
+        end
+
+        # Generate random alphanumeric text (fallback)
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param length [Integer] desired text length
+        # @return [String] generated alphanumeric text
+        #
+        def generate_random_alphanumeric(rng, length)
+          chars = ("a".."z").to_a + ("A".."Z").to_a + ("0".."9").to_a
+          length.times.map { rng.sample(chars) }.join
+        end
+      end
+
+      # Number type generator (integer or float)
+      #
+      # Generates numeric values with optional range constraints. Automatically
+      # detects whether to generate integers or floats based on the range.
+      #
+      # @example Integer range
+      #   number(1..100)  # Integer between 1 and 100
+      #
+      # @example Float range
+      #   number(0.0..1.0)  # Float between 0.0 and 1.0
+      #
+      # @example Named arguments
+      #   number(min: 10, max: 100)
+      #
+      class Number < Base
+        # Generate a random number
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @option args [Range] :range numeric range
+        # @option args [Integer, Float] :min minimum value
+        # @option args [Integer, Float] :max maximum value
+        # @return [Integer, Float] generated number
+        #
+        def generate_random(rng, context, args)
+          range = extract_range(args)
+          if range
+            # Detect if we need floats based on range values
+            if range.first.is_a?(Float) || range.last.is_a?(Float)
+              (rng.rand * (range.last - range.first)) + range.first
+            else
+              rng.int(range.first, range.last)
+            end
+          else
+            # Default: integer from 0 to 1000
+            rng.int(0, 1000)
+          end
+        end
+
+        # Generate edge case numbers
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Integer, Float] edge case number
+        #
+        def generate_edge(rng, context, args)
+          range = extract_range(args)
+          if range
+            # Return boundary values
+            candidates = [range.first, range.last]
+            rng.sample(candidates)
+          else
+            rng.sample(Generator::Modes::EDGE_NUMBERS)
+          end
+        end
+
+        # Generate invalid number values
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Object] invalid value
+        #
+        def generate_invalid(rng, context, args)
+          rng.sample(["not a number", nil, "NaN", Float::INFINITY, "", []])
+        end
+
+        # Generate hostile numeric values for security testing
+        #
+        # Returns extreme values designed to cause overflows,
+        # underflows, or unexpected behavior.
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Numeric] hostile numeric value
+        #
+        def generate_hostile(rng, context, args)
+          hostile_numbers = [
+            -2**63, # MIN_INT64
+            (2**63) - 1, # MAX_INT64
+            -2**31, # MIN_INT32
+            (2**31) - 1, # MAX_INT32
+            Float::INFINITY,
+            -Float::INFINITY,
+            Float::NAN,
+            0.0 / 0.0,
+            1.0 / 0.0,
+            -1.0 / 0.0,
+            2**128,             # Extreme large number
+            -2**128,
+            0.0000000000001,    # Very small float
+            9_999_999_999_999_999_999_999_999_999_999_999_999,
+            -9_999_999_999_999_999_999_999_999_999_999_999_999
+          ]
+          rng.sample(hostile_numbers)
+        end
+
+        private
+
+        # Extract range from arguments
+        #
+        # @param args [Hash] type arguments
+        # @return [Range, nil] extracted range
+        #
+        def extract_range(args)
+          if args[:range].is_a?(Range)
+            args[:range]
+          elsif args[:min] || args[:max]
+            min = args[:min] || 0
+            max = args[:max] || 100
+            min..max
+          elsif args[:value].is_a?(Range)
+            args[:value] # fallback
+          else
+            nil
+          end
+        end
+      end
+
+      # Boolean type generator
+      #
+      # Generates true/false values with optional probability weights.
+      #
+      # @example Default (50/50)
+      #   boolean
+      #
+      # @example With probability
+      #   boolean(true: 80%)  # 80% chance of true
+      #   boolean(false: 30%) # 30% chance of false
+      #
+      class Boolean < Base
+        # Generate a random boolean
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @option args [Integer] :true_probability probability of true (0-100)
+        # @option args [Integer] :false_probability probability of false (0-100)
+        # @return [Boolean] generated boolean value
+        #
+        def generate_random(rng, context, args)
+          true_prob = extract_probability(args[:true_probability] || args["true_probability"])
+          false_prob = extract_probability(args[:false_probability] || args["false_probability"])
+
+          threshold = if true_prob && true_prob > 0
+                        true_prob
+                      elsif false_prob && false_prob > 0
+                        100 - false_prob
+                      else
+                        50 # Default 50/50
+                      end
+
+          rng.int(1, 100) <= threshold
+        end
+
+        # Generate edge case boolean
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Boolean] edge case boolean
+        #
+        def generate_edge(rng, context, args)
+          rng.sample([true, false])
+        end
+
+        # Generate invalid boolean values
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Object] invalid value
+        #
+        def generate_invalid(rng, context, args)
+          rng.sample([nil, "true", "false", 0, 1, "", []])
+        end
+
+        private
+
+        # Extract probability from argument
+        #
+        # @param prob [Integer, String, nil] probability value
+        # @return [Integer, nil] extracted probability (0-100)
+        #
+        def extract_probability(prob)
+          return nil if prob.nil?
+
+          case prob
+          when Integer
+            prob.clamp(0, 100)
+          when String
+            prob.to_i.clamp(0, 100) # fallback
+          else
+            nil
+          end
+        end
+      end
+
+      # Const type generator - returns a literal constant value
+      #
+      # Always returns the exact value provided, regardless of generation mode.
+      # Useful for fields that should always have the same value, like
+      # discriminator fields or fixed identifiers.
+      #
+      # @example Fixed string value
+      #   type: const("message_create")
+      #
+      # @example Fixed number value
+      #   version: const(1)
+      #
+      # @example As discriminator
+      #   eventType: const("new_twitter_direct_message")
+      #
+      class Const < Base
+        # Generate the constant value
+        #
+        # @param rng [Generator::RNG] random number generator (not used)
+        # @param context [Generator::Context] generation context (not used)
+        # @param args [Hash] type arguments
+        # @option args [Object] :value the constant value to return
+        # @return [Object] the constant value
+        #
+        def generate(rng, context, args, mode)
+          extract_value(args)
+        end
+
+        # Generate random constant (same as generate)
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Object] the constant value
+        #
+        def generate_random(rng, context, args)
+          extract_value(args)
+        end
+
+        # Generate edge case constant (same as generate)
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Object] the constant value
+        #
+        def generate_edge(rng, context, args)
+          extract_value(args)
+        end
+
+        # Generate invalid constant (same as generate)
+        #
+        # For const types, even "invalid" mode returns the constant value,
+        # since the purpose is to always return the same value.
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Object] the constant value
+        #
+        def generate_invalid(rng, context, args)
+          extract_value(args)
+        end
+
+        private
+
+        # Extract the constant value from arguments
+        #
+        # @param args [Hash] type arguments
+        # @return [Object] the extracted value
+        #
+        def extract_value(args)
+          # Support multiple argument formats
+          args[:value] || args["value"] || args[:path] || args["path"] || args.values.first
+        end
+      end
+    end
+  end
+end