synthra 0.1.0

data/lib/synthra/schema.rb

@@ -0,0 +1,605 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Schema Class
+# =============================================================================
+#
+# This file defines the Schema class which represents a complete schema
+# definition parsed from DSL. A Schema contains fields, behaviors, and
+# provides methods for generating fake data.
+#
+# @example DSL definition
+#   User:
+#     @seed 12345
+#     @latency 50..100ms
+#     id: uuid
+#     name: name
+#     email: email
+#     age: number(18..80)
+#
+# @example Using a schema
+#   schema = Synthra.load("user.dsl")
+#   user = schema.generate
+#   users = schema.generate_many(100)
+#
+# =============================================================================
+
+
+module Synthra
+
+  # Represents a complete schema definition
+  #
+  # A Schema is the parsed representation of a DSL schema definition.
+  # It contains all the fields, behaviors, and metadata needed to generate
+  # fake data records.
+  #
+  # Schemas are typically created by loading DSL files through the Registry
+  # or Synthra.load, but can also be created programmatically.
+  #
+  # @example Load from file
+  #   schema = Synthra.load("schemas/user.dsl")
+  #
+  # @example Generate single record
+  #   user = schema.generate
+  #   # => { "id" => "550e8400-...", "name" => "John Doe", ... }
+  #
+  # @example Generate with options
+  #   user = schema.generate(
+  #     seed: 12345,          # Deterministic output
+  #     mode: :edge,          # Edge case values
+  #     overrides: { "name" => "Custom Name" }
+  #   )
+  #
+  # @example Generate multiple records
+  #   users = schema.generate_many(100, seed: 42)
+  #   # => [{ "id" => "...", ... }, { "id" => "...", ... }, ...]
+  #
+  # @example With runtime behaviors
+  #   slow_schema = schema.with_behavior(:latency, 500..1000)
+  #   user = slow_schema.generate  # Will have 500-1000ms delay
+  #
+
+  class Schema
+
+    # @!attribute [r] name
+    #   The schema name (from DSL: "User:")
+    #   @return [String] schema name
+
+    attr_reader :name
+
+
+    # @!attribute [r] fields
+    #   All fields defined in this schema
+    #   @return [Array<Field>] list of Field objects
+
+    attr_reader :fields
+
+
+    # @!attribute [r] behaviors
+    #   Schema-level behaviors defined in DSL
+    #   @return [Array<Hash>] list of behavior hashes ({ name:, value: })
+
+    attr_reader :behaviors
+
+
+    # @!attribute [r] metadata
+    #   Additional metadata (seed, etc.)
+    #   @return [Hash] metadata key-value pairs
+
+    attr_reader :metadata
+
+
+    # @!attribute [r] version
+    #   Schema version from @version annotation
+    #   @return [String, nil] version string or nil if not specified
+
+    attr_reader :version
+
+
+    # @!attribute [r] deprecated
+    #   Whether this schema is deprecated
+    #   @return [Boolean] true if schema has @deprecated annotation
+
+    attr_reader :deprecated
+
+
+    # @!attribute [r] deprecation_message
+    #   Deprecation message if schema is deprecated
+    #   @return [String, nil] deprecation message or nil
+
+    attr_reader :deprecation_message
+
+
+    # Create a new Schema instance
+    #
+    # @param name [String] the schema name
+    # @param fields [Array<Field>] field definitions
+    # @param behaviors [Array<Hash>] schema-level behaviors
+    # @param metadata [Hash] additional metadata
+    # @param version [String, nil] schema version
+    # @param deprecated [Boolean] whether schema is deprecated
+    # @param deprecation_message [String, nil] deprecation message
+    #
+    # @example
+    #   schema = Schema.new(
+    #     name: "User",
+    #     fields: [
+    #       Field.new(name: "id", type_name: "uuid"),
+    #       Field.new(name: "name", type_name: "name")
+    #     ],
+    #     behaviors: [{ name: :latency, value: 100 }],
+    #     version: "1.0"
+    #   )
+    #
+
+    def initialize(name:, fields: [], behaviors: [], metadata: {}, version: nil, deprecated: false, deprecation_message: nil)
+      @name = name
+      @fields = fields
+      @behaviors = behaviors
+      @metadata = metadata
+      @version = version
+      @deprecated = deprecated
+      @deprecation_message = deprecation_message
+      @runtime_behaviors = []
+    end
+
+
+    # Check if schema is deprecated
+    #
+    # @return [Boolean] true if deprecated
+    #
+
+    def deprecated?
+      @deprecated
+    end
+
+
+    # Get schema info hash for display
+    #
+    # @return [Hash] schema information
+    #
+
+    def info
+      {
+        name: @name,
+        version: @version,
+        deprecated: @deprecated,
+        deprecation_message: @deprecation_message,
+        field_count: @fields.length,
+        behavior_count: @behaviors.length,
+        fields: @fields.map(&:name)
+      }
+    end
+
+
+    # Get a field by name
+    #
+    # @param field_name [String, Symbol] the field name to find
+    # @return [Field, nil] the field or nil if not found
+    #
+    # @example
+    #   email_field = schema.field("email")
+    #   email_field.type_name  # => "email"
+    #
+
+    def field(field_name)
+      fields.find { |f| f.name == field_name.to_s }
+    end
+
+
+    # Get all required (non-optional) fields
+    #
+    # @return [Array<Field>] fields that are not marked as optional
+    #
+    # @example
+    #   schema.required_fields.each do |field|
+    #     puts "#{field.name} is required"
+    #   end
+    #
+
+    def required_fields
+      fields.reject(&:optional?)
+    end
+
+
+    # Get all optional fields
+    #
+    # @return [Array<Field>] fields marked with ? suffix
+    #
+    # @example
+    #   schema.optional_fields.each do |field|
+    #     puts "#{field.name} is optional"
+    #   end
+    #
+
+    def optional_fields
+      fields.select(&:optional?)
+    end
+
+
+    # Generate a single record
+    #
+    # Creates one fake data record based on the schema definition.
+    # The record is a Hash with field names as keys.
+    #
+    # @param seed [Integer, nil] random seed for deterministic output
+    # @param mode [Symbol, nil] generation mode (:random, :edge, :invalid, :mixed)
+    #   Defaults to Synthra.configuration.default_mode
+    # @param overrides [Hash] field values to use instead of generating
+    # @param registry [Registry, nil] registry for resolving cross-schema references
+    # @return [Hash] the generated record
+    #
+    # @example Basic generation
+    #   user = schema.generate
+    #   # => { "id" => "550e8400-...", "name" => "John Doe", "email" => "john@..." }
+    #
+    # @example Deterministic generation
+    #   user1 = schema.generate(seed: 12345)
+    #   user2 = schema.generate(seed: 12345)
+    #   user1 == user2  # => true
+    #
+    # @example With overrides
+    #   user = schema.generate(overrides: { "name" => "Test User" })
+    #   user["name"]  # => "Test User"
+    #
+    # @example Edge case mode
+    #   user = schema.generate(mode: :edge)
+    #   # May contain empty strings, nil values, boundary values
+    #
+
+    def generate(seed: nil, mode: nil, overrides: {}, registry: nil, depth: 0, resolver: nil, parent_context: nil, shared_context: nil)
+      mode ||= Synthra.configuration.default_mode
+      # Inherit shared_context from parent_context if not explicitly provided
+      shared_context ||= parent_context&.instance_variable_get(:@shared_context)
+      engine = Generator::Engine.new(self, registry: registry, resolver: resolver)
+      result = engine.generate(seed: seed, mode: mode, overrides: overrides, depth: depth, parent_context: parent_context, shared_context: shared_context)
+      apply_behaviors(result, engine.rng)
+    end
+
+
+    # Generate multiple records
+    #
+    # Creates multiple fake data records in a batch. More efficient
+    # than calling generate() multiple times.
+    #
+    # @param count [Integer] number of records to generate
+    # @param seed [Integer, nil] random seed for deterministic output
+    # @param mode [Symbol, nil] generation mode
+    # @param overrides [Hash] field values to override for all records
+    # @param registry [Registry, nil] registry for cross-schema references
+    # @return [Array<Hash>] array of generated records
+    #
+    # @example Generate 100 users
+    #   users = schema.generate_many(100)
+    #   users.length  # => 100
+    #
+    # @example Deterministic batch
+    #   users1 = schema.generate_many(10, seed: 42)
+    #   users2 = schema.generate_many(10, seed: 42)
+    #   users1 == users2  # => true
+    #
+
+    def generate_many(count, seed: nil, mode: nil, overrides: {}, registry: nil, shared_context: nil, engine: nil, locale: "en", threads: nil)
+      mode ||= Synthra.configuration.default_mode
+      
+      # Use native engine if requested and available
+      if engine == :native
+        return generate_many_native(count, seed: seed, locale: locale, threads: threads)
+      end
+      
+      # ponytail: fast_mode once selected a Generator::FastEngine that was never implemented (it
+      # crashed). The real high-throughput path is the native Rust engine (engine: :native); the
+      # standard engine handles everything else.
+      gen = Generator::Engine.new(self, registry: registry)
+
+      gen.generate_many(count, seed: seed, mode: mode, overrides: overrides, shared_context: shared_context)
+    end
+
+
+    # Generate multiple records using the Native Rust engine (maximum performance)
+    #
+    # Uses the Rust native extension with fake-rs for 100-250x faster generation.
+    # Requires the native extension to be compiled.
+    #
+    # @param count [Integer] number of records to generate
+    # @param seed [Integer, nil] random seed for deterministic output
+    # @param locale [String] locale for data generation (en, fr_fr, de_de, ja_jp, etc.)
+    # @param threads [Integer, nil] number of threads (nil/0 = use all cores)
+    # @return [Array<Hash>] array of generated records
+    # @raise [LoadError] if native extension is not available
+    #
+    # @example Native engine generation
+    #   users = schema.generate_many_native(1_000_000, seed: 42)
+    #
+    # @example With locale
+    #   users = schema.generate_many_native(100_000, locale: "ja_jp")
+    #
+    # @example With limited threads
+    #   users = schema.generate_many_native(100_000, threads: 4)
+    #
+
+    def generate_many_native(count, seed: nil, locale: "en", threads: nil)
+      native_engine = NativeEngine.new(self, locale: locale, threads: threads)
+      native_engine.generate_many(count, seed: seed)
+    end
+
+
+    # Generate records directly to a file using the Native Rust engine
+    #
+    # This is the most efficient method for generating large amounts of data.
+    # Uses the Rust native extension for maximum performance.
+    #
+    # @param count [Integer] number of records to generate
+    # @param path [String] output file path
+    # @param seed [Integer, nil] random seed for deterministic output
+    # @param locale [String] locale for data generation
+    # @param format [String] output format: "jsonl", "json", "csv"
+    # @param threads [Integer, nil] number of threads (nil/0 = use all cores)
+    # @return [Integer] number of records written
+    # @raise [LoadError] if native extension is not available
+    #
+    # @example Generate 10 million records to JSONL
+    #   schema.generate_to_file(10_000_000, "users.jsonl", format: "jsonl")
+    #
+    # @example Generate CSV with seed
+    #   schema.generate_to_file(1_000_000, "users.csv", seed: 42, format: "csv")
+    #
+    # @example Generate with limited threads (leaves other cores free)
+    #   schema.generate_to_file(10_000_000, "users.jsonl", threads: 4)
+    #
+
+    def generate_to_file(count, path, seed: nil, locale: "en", format: "jsonl", threads: nil)
+      native_engine = NativeEngine.new(self, locale: locale, threads: threads)
+      native_engine.generate_to_file(count, path, seed: seed, format: format)
+    end
+
+
+    # Generate multiple records using FastEngine (high performance)
+    #
+    # Uses the optimized FastEngine for 2-3x faster generation.
+    # NOT thread-safe - use only in single-threaded contexts.
+    #
+    # @param count [Integer] number of records to generate
+    # @param seed [Integer, nil] random seed for deterministic output
+    # @param mode [Symbol, nil] generation mode
+    # @param overrides [Hash] field values to override for all records
+    # @param registry [Registry, nil] registry for cross-schema references
+    # @return [Array<Hash>] array of generated records
+    #
+    # @example Fast batch generation
+    #   users = schema.generate_many_fast(100_000, seed: 42)
+    #
+
+    def generate_many_fast(count, seed: nil, mode: nil, overrides: {}, registry: nil)
+      mode ||= Synthra.configuration.default_mode
+      # ponytail: kept as an alias for the standard engine — FastEngine was never implemented.
+      engine = Generator::Engine.new(self, registry: registry)
+      engine.generate_many(count, seed: seed, mode: mode, overrides: overrides)
+    end
+
+
+    # Generate multiple records as a lazy stream (Enumerator)
+    #
+    # Returns an Enumerator that generates records on-demand. This is
+    # memory-efficient for large batches as records are not all held
+    # in memory at once.
+    #
+    # @param count [Integer] total number of records to generate
+    # @param seed [Integer, nil] random seed for deterministic output
+    # @param mode [Symbol, nil] generation mode
+    # @param overrides [Hash] field values to override for all records
+    # @param registry [Registry, nil] registry for cross-schema references
+    # @return [Enumerator] lazy enumerator of records
+    #
+    # @example Stream processing for large batches
+    #   schema.generate_many_stream(10000, seed: 42).each do |record|
+    #     process(record)  # Records generated one at a time
+    #   end
+    #
+    # @note For small batches (< 1000 records), generate_many is more efficient.
+    #   Use generate_many_stream for large batches to reduce memory usage.
+    #
+
+    def generate_many_stream(count, seed: nil, mode: nil, overrides: {}, registry: nil, shared_context: nil)
+      mode ||= Synthra.configuration.default_mode
+      
+      # ponytail: fast_mode's FastEngine was never implemented; use the standard engine.
+      engine = Generator::Engine.new(self, registry: registry)
+
+      engine.generate_many_stream(count, seed: seed, mode: mode, overrides: overrides, shared_context: shared_context)
+    end
+
+
+    # Generate stream using FastEngine (high performance)
+    #
+    # Uses the optimized FastEngine for 2-3x faster streaming.
+    # NOT thread-safe - use only in single-threaded contexts.
+    #
+    # @param count [Integer] number of records to generate
+    # @param seed [Integer, nil] random seed for deterministic output
+    # @param mode [Symbol, nil] generation mode
+    # @param overrides [Hash] field values to override for all records
+    # @param registry [Registry, nil] registry for cross-schema references
+    # @return [Enumerator] lazy enumerator of records
+    #
+    # @example Fast streaming
+    #   schema.generate_stream_fast(1_000_000, seed: 42).each do |record|
+    #     process(record)
+    #   end
+    #
+
+    def generate_stream_fast(count, seed: nil, mode: nil, overrides: {}, registry: nil)
+      mode ||= Synthra.configuration.default_mode
+      # ponytail: kept as an alias for the standard engine — FastEngine was never implemented.
+      engine = Generator::Engine.new(self, registry: registry)
+      engine.generate_many_stream(count, seed: seed, mode: mode, overrides: overrides)
+    end
+
+
+    # Generate a record as a JSON string
+    #
+    # Convenience method that generates a record and serializes it to JSON.
+    #
+    # @param pretty [Boolean] if true, format with indentation
+    # @param options [Hash] additional options passed to generate()
+    # @return [String] JSON string
+    #
+    # @example Minified JSON
+    #   json = schema.generate_json
+    #   # => '{"id":"550e8400-...","name":"John Doe"}'
+    #
+    # @example Pretty-printed JSON
+    #   json = schema.generate_json(pretty: true)
+    #   # => '{\n  "id": "550e8400-...",\n  "name": "John Doe"\n}'
+    #
+
+    def generate_json(pretty: false, **options)
+      result = generate(**options)
+      if pretty
+        JSON.pretty_generate(result)
+      else
+        JSON.generate(result)
+      end
+    end
+
+
+    # Generate records as a lazy stream (Enumerator)
+    #
+    # Returns an Enumerator that generates records on-demand. This is
+    # memory-efficient for large batches as records are not all held
+    # in memory at once.
+    #
+    # @param count [Integer] total number of records to generate
+    # @param options [Hash] generation options (seed, mode, etc.)
+    # @return [Enumerator] lazy enumerator of records
+    #
+    # @example Stream processing
+    #   schema.generate_stream(count: 10000).each do |record|
+    #     process(record)  # Records generated one at a time
+    #   end
+    #
+    # @example Convert to NDJSON
+    #   schema.generate_stream(count: 1000).each do |record|
+    #     puts record.to_json
+    #   end
+    #
+
+    def generate_stream(count:, **options)
+      Generator::Streamer.new(self, **options).generate_stream(count: count)
+    end
+
+
+    # Create a new schema with an additional runtime behavior
+    #
+    # Returns a new Schema instance with the behavior added. The original
+    # schema is not modified.
+    #
+    # @param name [Symbol, String] behavior name (:latency, :failure, etc.)
+    # @param value [Object] behavior configuration value
+    # @return [Schema] new schema with the behavior added
+    #
+    # @example Add latency behavior
+    #   slow_schema = schema.with_behavior(:latency, 500..1000)
+    #   slow_schema.generate  # Will have 500-1000ms delay
+    #
+    # @example Chain multiple behaviors
+    #   test_schema = schema
+    #     .with_behavior(:latency, 100)
+    #     .with_behavior(:failure, 10)
+    #
+
+    def with_behavior(name, value)
+      new_schema = dup
+      new_schema.instance_variable_set(
+        :@runtime_behaviors,
+        @runtime_behaviors + [{ name: name.to_sym, value: value }]
+      )
+      new_schema
+    end
+
+
+    # Get all behaviors (defined in DSL + added at runtime)
+    #
+    # @return [Array<Hash>] all behavior configurations
+    #
+    # @example
+    #   schema.all_behaviors
+    #   # => [{ name: :latency, value: 100 }, { name: :seed, value: 12345 }]
+    #
+
+    def all_behaviors
+      behaviors + @runtime_behaviors
+    end
+
+
+    # Check if schema has a specific behavior
+    #
+    # @param name [Symbol, String] behavior name to check
+    # @return [Boolean] true if the behavior is defined
+    #
+    # @example
+    #   schema.has_behavior?(:latency)  # => true
+    #   schema.has_behavior?(:failure)  # => false
+    #
+
+    def has_behavior?(name)
+      all_behaviors.any? { |b| b[:name] == name.to_sym }
+    end
+
+
+    # Get a specific behavior configuration
+    #
+    # @param name [Symbol, String] behavior name
+    # @return [Hash, nil] the behavior hash or nil if not found
+    #
+    # @example
+    #   latency = schema.behavior(:latency)
+    #   latency[:value]  # => 100..500
+    #
+
+    def behavior(name)
+      all_behaviors.find { |b| b[:name] == name.to_sym }
+    end
+
+
+    # Get the seed from metadata if specified
+    #
+    # @return [Integer, nil] the seed value or nil
+    #
+    # @example
+    #   # DSL: @seed 12345
+    #   schema.seed  # => 12345
+    #
+
+    def seed
+      metadata[:seed]
+    end
+
+
+    # String representation
+    #
+    # @return [String] summary of the schema
+    #
+
+    def to_s
+      "#<Schema #{name} fields=#{fields.length} behaviors=#{all_behaviors.length}>"
+    end
+
+    alias inspect to_s
+
+    private
+
+
+    # Apply schema-level behaviors to generated result
+    #
+    # @param result [Hash] the generated record
+    # @param rng [Generator::RNG] random number generator
+    # @return [Hash] the result after applying behaviors
+    #
+
+    def apply_behaviors(result, rng)
+      Behaviors::Applicator.new(self, rng).apply_schema_behaviors(result)
+    end
+  end
+end

data/lib/synthra/schema_inheritance.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Synthra
+  # Schema Inheritance Support
+  #
+  # Allows schemas to inherit fields from parent schemas using the < operator.
+  #
+  # @example DSL syntax
+  #   BaseUser:
+  #     id: uuid
+  #     created_at: timestamp
+  #
+  #   AdminUser < BaseUser:
+  #     role: const("admin")
+  #     permissions: array(text, 1..5)
+  #
+  module SchemaInheritance
+    # Resolve inheritance for a schema node
+    #
+    # @param schema_node [AST::SchemaNode] the schema node to process
+    # @param registry [Registry] the registry containing parent schemas
+    # @return [AST::SchemaNode] schema node with inherited fields
+    #
+    def self.resolve(schema_node, registry)
+      return schema_node unless schema_node.parent_name
+
+      parent_schema = registry.schema(schema_node.parent_name)
+      
+      # Merge parent fields with child fields (child fields override parent)
+      parent_field_names = parent_schema.fields.map(&:name)
+      child_field_names = schema_node.fields.map { |f| f.respond_to?(:name) ? f.name : f[:name] }
+      
+      # Get parent fields that aren't overridden
+      inherited_fields = parent_schema.fields.reject do |f|
+        child_field_names.include?(f.name)
+      end
+      
+      # Create new schema node with merged fields
+      # Parent fields come first, then child fields
+      merged_fields = []
+      
+      # Add inherited fields
+      inherited_fields.each do |field|
+        merged_fields << convert_field_to_node(field)
+      end
+      
+      # Add child's own fields
+      schema_node.fields.each do |field|
+        merged_fields << field
+      end
+      
+      # Create new schema node with merged fields
+      Parser::AST::SchemaNode.new(
+        name: schema_node.name,
+        fields: merged_fields,
+        behaviors: schema_node.behaviors,
+        parent_name: schema_node.parent_name,
+        line: schema_node.line
+      )
+    end
+
+    # Convert a Field object to a field node (for inheritance)
+    #
+    # @param field [Field] the field to convert
+    # @return [Parser::AST::FieldNode] the field node
+    #
+    def self.convert_field_to_node(field)
+      Parser::AST::FieldNode.new(
+        name: field.name,
+        type_node: Parser::AST::TypeNode.new(
+          name: field.type_name,
+          arguments: field.type_args,
+          nullable: field.nullable?,
+          line: 0
+        ),
+        optional: field.optional?,
+        condition: nil,
+        behaviors: [],
+        line: 0
+      )
+    end
+
+    # Parse inheritance syntax from schema name
+    #
+    # @param name [String] the schema name potentially with inheritance
+    # @return [Array<String, String>] [schema_name, parent_name or nil]
+    #
+    # @example
+    #   parse_inheritance("AdminUser < BaseUser")
+    #   # => ["AdminUser", "BaseUser"]
+    #
+    #   parse_inheritance("User")
+    #   # => ["User", nil]
+    #
+    def self.parse_inheritance(name)
+      if name.include?("<")
+        parts = name.split("<").map(&:strip)
+        [parts[0], parts[1]]
+      else
+        [name, nil]
+      end
+    end
+  end
+end