synthra 0.1.0

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

@@ -0,0 +1,466 @@
+# frozen_string_literal: true
+
+module Synthra
+  module Types
+    module Core
+      # Copy type generator - copies value from another field in current or parent schema
+      #
+      # Allows referencing fields that were already generated in the same or parent schema.
+      # Useful for linking IDs across nested objects.
+      #
+      # @example Copy a nested field value
+      #   sender_id: copy("users.sender.id")
+      #
+      class Copy < Base
+        # Generate by copying from another field
+        #
+        # @param rng [Generator::RNG] random number generator (not used)
+        # @param context [Generator::Context] generation context with field values
+        # @param args [Hash] type arguments
+        # @option args [String] :path dot-separated path to field (e.g., "users.sender.id")
+        # @return [Object, nil] copied value
+        #
+        def generate(rng, context, args, mode)
+          path = args[:path] || args["path"] || args.values.first
+          return nil unless path && context
+
+          # Try current context first
+          result = context.get(path.to_s)
+          return result if result
+
+          # Walk up parent contexts to find the value
+          parent = context.parent_context
+          while parent && result.nil?
+            result = parent.get(path.to_s)
+            parent = parent.parent_context
+          end
+
+          result
+        end
+
+        def generate_random(rng, context, args)
+          generate(rng, context, args, :random)
+        end
+
+        def generate_edge(rng, context, args)
+          generate(rng, context, args, :edge)
+        end
+
+        def generate_invalid(rng, context, args)
+          nil
+        end
+      end
+
+      # Reference type generator (Ref(Schema.field))
+      #
+      # Generates values by resolving references to fields in other schemas.
+      # Uses the Resolver to look up previously generated values or generate
+      # new ones on-demand.
+      #
+      # @example Generate reference value
+      #   ref_type = Reference.new
+      #   ref_type.generate(rng, context, { ref: RefNode.new("User", "id") }, :random)
+      #
+      class Reference < Base
+        # Generate a reference value
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @option args [ReferenceNode, Hash] :ref reference node or hash with :schema and :field
+        # @return [Object, nil] resolved reference value
+        #
+        def generate(rng, context, args, mode)
+          ref = args[:ref] || args["ref"]
+          return nil unless ref
+
+          # Extract schema name and field path
+          if ref.respond_to?(:schema_name) && ref.respond_to?(:field_path)
+            schema_name = ref.schema_name
+            field_path = ref.field_path
+          elsif ref.is_a?(Hash)
+            schema_name = ref[:schema] || ref["schema"]
+            field_path = ref[:field] || ref["field"]
+          else
+            return nil
+          end
+
+          return nil unless schema_name && field_path
+
+          # Get resolver from context
+          resolver = context&.resolver
+          return nil unless resolver
+
+          # :nocov: context is non-nil here (the `return nil unless resolver` guard above
+          # exits when context — and thus resolver — is nil), so this `&.` else is unreachable.
+          depth = context&.depth || 0
+          # :nocov:
+          # Derive a deterministic seed from the (seeded) generation RNG so the referenced record —
+          # and thus this FK value — is reproducible by seed, mirroring how Shared seeds its
+          # sub-generation. Without it the resolver generated the referenced schema with a random
+          # seed, so ref(User.id) varied across runs with the same parent seed.
+          resolver.resolve(schema_name, field_path, depth: depth, seed: rng.int(0, 2_147_483_647))
+
+        rescue StandardError
+          nil
+        end
+
+
+        # Generate a random reference value
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Object, nil] resolved reference value
+        #
+        def generate_random(rng, context, args)
+          generate(rng, context, args, :random)
+        end
+
+        # Generate edge case reference values
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Object, nil] edge case value
+        #
+        def generate_edge(rng, context, args)
+          nil
+        end
+
+        # Generate invalid reference values
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Object] invalid reference value
+        #
+        def generate_invalid(rng, context, args)
+          rng.sample([
+            nil,
+            "invalid-ref",
+            123,
+            []
+          ])
+        end
+      end
+
+      # Shared type generator - generates once and reuses across batch
+      #
+      # When used with generate_many, generates the wrapped type once per batch
+      # and reuses the same value for all records. Useful for scenarios like
+      # "all DMs go to the same recipient" or "all orders from same customer".
+      #
+      # @example All records share the same recipient
+      #   users: map_by_field("id", sender: TwitterUser, recipient: shared(TwitterUser))
+      #
+      class Shared < Base
+        # Track whether we've already warned about misuse (to avoid spam)
+        @warned_about_misuse = false
+
+        class << self
+          attr_accessor :warned_about_misuse
+        end
+
+        # Generate a shared value (cached per batch)
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context with shared_context
+        # @param args [Hash] type arguments
+        # @option args [String] :type_name the wrapped type to generate
+        # @option args [Hash] :type_args arguments for the wrapped type
+        # @return [Object] generated or cached value
+        #
+        def generate(rng, context, args, mode)
+          type_name = args[:type_name] || args["type_name"]
+          type_args = args[:type_args] || args["type_args"] || {}
+          shared_key = args[:shared_key] || args["shared_key"] || "#{type_name}_#{type_args.hash}"
+
+          # Get or create shared_context from context
+          shared_context = context&.shared_context
+
+          # Warn if shared_context was not initialized by generate_many
+          if shared_context.nil? && should_warn_about_misuse?
+            emit_misuse_warning(type_name)
+            shared_context = {}
+          end
+
+          shared_context ||= {}
+
+          # Return cached value if exists
+          return shared_context[shared_key] if shared_context.key?(shared_key)
+
+          # Generate new value
+          registry = context&.registry
+
+          value = if registry&.schema?(type_name)
+                    # It's a schema reference
+                    schema = registry.schema(type_name)
+                    new_seed = rng.int(0, 2_147_483_647)
+                    schema.generate(seed: new_seed, registry: registry, mode: mode, parent_context: context)
+                  else
+                    # It's a regular type
+                    type_gen = Types::Registry.lookup(type_name)
+                    type_gen.generate(rng, context, type_args, mode)
+                  end
+
+          # Cache the value
+          shared_context[shared_key] = value
+          context.shared_context = shared_context if context
+
+          value
+        end
+
+        def generate_random(rng, context, args)
+          generate(rng, context, args, :random)
+        end
+
+        def generate_edge(rng, context, args)
+          generate(rng, context, args, :edge)
+        end
+
+        def generate_invalid(rng, context, args)
+          nil
+        end
+
+        private
+
+        # Check if we should warn about shared() misuse
+        #
+        # @return [Boolean] true if warning should be emitted
+        #
+        def should_warn_about_misuse?
+          return false if self.class.warned_about_misuse
+
+          Synthra.configuration.warn_on_shared_misuse
+        end
+
+        # Emit warning about shared() being used outside generate_many()
+        #
+        # @param type_name [String] the type name being shared
+        # @return [void]
+        #
+        def emit_misuse_warning(type_name)
+          self.class.warned_about_misuse = true
+
+          message = "[Synthra] Warning: shared(#{type_name}) used outside generate_many() - " \
+                    "value will not be shared across calls. " \
+                    "Use generate_many() for batch generation with shared values."
+
+          logger = Synthra.configuration.logger
+          if logger
+            logger.warn(message)
+          else
+            warn message
+          end
+        end
+      end
+
+      # Schema reference type generator (schema(:Name))
+      #
+      # Generates values by instantiating another schema. This is the explicit
+      # way to reference schemas in the new Simulyra DSL syntax.
+      #
+      # @example Generate schema reference
+      #   schema_ref = SchemaRef.new
+      #   schema_ref.generate(rng, context, { schema_name: "User", array: false }, :random)
+      #
+      # @example Generate array of schemas
+      #   schema_ref.generate(rng, context, { schema_name: "User", array: true, array_range: 1..10 }, :random)
+      #
+      class SchemaRef < Base
+        # Generate a schema reference value
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @option args [String] :schema_name name of the schema to generate
+        # @option args [Boolean] :array whether to generate an array (default: false)
+        # @option args [Range, nil] :array_range size range for arrays
+        # @return [Object, Array<Object>, nil] generated schema instance(s)
+        #
+        def generate(rng, context, args, mode)
+          schema_name = args[:schema_name] || args["schema_name"]
+          return nil unless schema_name
+
+          registry = context&.registry
+          return nil unless registry
+
+          # Check if schema exists
+          unless registry.schema?(schema_name)
+            return nil
+          end
+
+          schema = registry.schema(schema_name)
+          is_array = args[:array] || args["array"] || false
+          array_range = args[:array_range] || args["array_range"]
+
+          if is_array
+            generate_array(rng, context, schema, registry, mode, array_range)
+          else
+            generate_single(rng, context, schema, registry, mode)
+          end
+        end
+
+        def generate_random(rng, context, args)
+          generate(rng, context, args, :random)
+        end
+
+        def generate_edge(rng, context, args)
+          generate(rng, context, args, :edge)
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([
+            nil,
+            "invalid-schema-ref",
+            123,
+            []
+          ])
+        end
+
+        private
+
+        # Generate a single schema instance
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param schema [Schema] the schema to generate
+        # @param registry [Registry] schema registry
+        # @param mode [Symbol] generation mode
+        # @return [Object] generated schema instance
+        #
+        def generate_single(rng, context, schema, registry, mode)
+          new_seed = rng.int(0, 2_147_483_647)
+          # :nocov: every caller reaches here only past `return nil unless registry`
+          # (registry derives from context), so context is non-nil — `&.` else unreachable.
+          depth = (context&.depth || 0) + 1
+          # :nocov:
+
+          # Prevent infinite recursion
+          # :nocov: Synthra.configuration and #limits are memoized (`||= …`) and never nil,
+          # so the `&.` nil-receiver else-arms on this chain are unreachable.
+          max_depth = Synthra.configuration&.limits&.max_recursion || 10
+          # :nocov:
+          return nil if depth > max_depth
+
+          schema.generate(
+            seed: new_seed,
+            registry: registry,
+            mode: mode,
+            parent_context: context,
+            depth: depth
+          )
+        end
+
+        # Generate an array of schema instances
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param schema [Schema] the schema to generate
+        # @param registry [Registry] schema registry
+        # @param mode [Symbol] generation mode
+        # @param size_range [Range, nil] size range for the array
+        # @return [Array<Object>] array of generated schema instances
+        #
+        def generate_array(rng, context, schema, registry, mode, size_range)
+          # Determine array size
+          size = if size_range.is_a?(Range)
+                   rng.int(size_range.min, size_range.max)
+                 elsif size_range.is_a?(Integer)
+                   size_range
+                 elsif size_range.is_a?(Hash)
+                   min = size_range[:min] || 0
+                   max = size_range[:max] || 10
+                   rng.int(min, max)
+                 else
+                   rng.int(1, 10)  # Default size
+                 end
+
+          # Enforce array size limits
+          # :nocov: Synthra.configuration and #limits are memoized (`||= …`) and never nil,
+          # so the `&.` nil-receiver else-arms on this chain are unreachable.
+          max_size = Synthra.configuration&.limits&.max_array_size || 1000
+          # :nocov:
+          size = [size, max_size].min
+
+          Array.new(size) do
+            generate_single(rng, context, schema, registry, mode)
+          end.compact
+        end
+      end
+
+      # Custom type generator (calls registered functions)
+      #
+      # Generates values by invoking a registered function with the current
+      # generation context. Functions can access previously generated fields
+      # to compute derived values.
+      #
+      # @example Generate using custom function
+      #   custom_type = Custom.new
+      #   custom_type.generate(rng, context, { function: :full_name }, :random)
+      #
+      class Custom < Base
+        # Generate a value using a custom function
+        #
+        # @param rng [Generator::RNG] random number generator (not used)
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @option args [Symbol, String] :function function name to call
+        # @return [Object] function result
+        # @raise [MissingFunctionError] if function not found
+        #
+        def generate(rng, context, args, mode)
+          function_name = args[:function] || args["function"] || args.values.first
+          raise Errors::MissingFunctionError.new(function_name) unless function_name
+
+          Functions::Registry.call(function_name.to_sym, context)
+        end
+
+        # Generate a random value using a custom function
+        #
+        # @param rng [Generator::RNG] random number generator (not used)
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Object] function result
+        # @raise [MissingFunctionError] if function not found
+        #
+        def generate_random(rng, context, args)
+          generate(rng, context, args, :random)
+        end
+
+        # Generate edge case custom values
+        #
+        # @param rng [Generator::RNG] random number generator
+        # @param context [Generator::Context] generation context
+        # @param args [Hash] type arguments
+        # @return [Object] edge case value
+        #
+        def generate_edge(rng, context, args)
+          generate(rng, context, args, :edge)
+
+        rescue StandardError
+          nil
+        end
+
+
+        # Generate invalid custom 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,
+            "invalid-custom",
+            123,
+            []
+          ])
+        end
+      end
+    end
+  end
+end
+