synthra 0.1.0

data/lib/synthra/registry.rb

@@ -0,0 +1,533 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Registry
+# =============================================================================
+#
+# The Registry class manages loading and storing multiple schema definitions.
+# It's essential for handling cross-schema references (Ref(User.id)) and
+# for organizing related schemas.
+#
+# @example Loading multiple schemas
+#   registry = Synthra::Registry.new
+#   registry.load_file("schemas/user.dsl")
+#   registry.load_file("schemas/order.dsl")
+#
+#   user = registry.schema("User").generate
+#   order = registry.schema("Order").generate(registry: registry)
+#
+# =============================================================================
+
+
+module Synthra
+
+  # Registry for storing and managing multiple schemas
+  #
+  # The Registry provides a central store for schema definitions, enabling:
+  # - Loading multiple DSL files
+  # - Cross-schema references (Ref(User.id))
+  # - Schema lookup by name
+  # - Enumeration of all schemas
+  #
+  # When generating data with cross-schema references, pass the registry
+  # to the generate method to enable reference resolution.
+  #
+  # @example Basic usage
+  #   registry = Synthra::Registry.new
+  #   registry.load_file("schemas/user.dsl")
+  #   
+  #   user_schema = registry.schema("User")
+  #   user = user_schema.generate
+  #
+  # @example Multiple schemas with references
+  #   registry = Synthra::Registry.new
+  #   registry.load_file("schemas/user.dsl")      # User: id, name, ...
+  #   registry.load_file("schemas/order.dsl")     # Order: user_id: Ref(User.id)
+  #   
+  #   order = registry.schema("Order").generate(registry: registry)
+  #   # order["user_id"] will be a generated User.id
+  #
+  # @example Iterating over schemas
+  #   registry.each do |name, schema|
+  #     puts "Schema: #{name} with #{schema.fields.length} fields"
+  #   end
+  #
+
+  class Registry
+
+    # Create a new empty registry
+    #
+    # @return [Registry] a new registry instance
+    #
+    # @example
+    #   registry = Synthra::Registry.new
+    #   registry.size  # => 0
+    #
+
+    def initialize
+      @schemas = {}
+      @mutex = Mutex.new
+      @ast_cache = {}
+      @cache_mutex = Mutex.new
+      @max_cache_size = Synthra.configuration.registry_cache_size
+    end
+
+
+    # Load schemas from a DSL file
+    #
+    # Reads and parses the DSL file, adding all schemas defined in it
+    # to the registry. Existing schemas with the same name will be
+    # overwritten.
+    #
+    # @param path [String] path to the DSL file (relative or absolute)
+    # @param validate [Boolean] whether to validate copy() paths (default: config setting)
+    # @return [Array<Schema>] the schemas that were loaded
+    # @raise [Errors::ParseError] if the DSL syntax is invalid
+    # @raise [Errors::SyntaxError] if there are syntax errors
+    # @raise [Errors::PathError] if copy() path validation fails
+    # @raise [Errno::ENOENT] if the file doesn't exist
+    #
+    # @example
+    #   registry.load_file("schemas/user.dsl")
+    #   # => [#<Schema User fields=5 behaviors=0>]
+    #
+    # @example Handle errors
+    #   begin
+    #     registry.load_file("invalid.dsl")
+    #   rescue Synthra::ParseError => e
+    #     puts "Error at line #{e.line}: #{e.message}"
+    #   end
+    #
+    # @example Skip validation
+    #   registry.load_file("schema.dsl", validate: false)
+    #
+
+    def load_file(path, validate: Synthra.configuration.validate_paths_on_load)
+      schemas = @mutex.synchronize do
+        load_file_unsafe(path)
+      end
+
+      # Validate paths outside mutex to avoid deadlock
+      validate_paths! if validate
+
+      schemas
+    end
+
+    private
+
+    def load_file_unsafe(path)
+
+      # Check cache first
+      cache_key = File.expand_path(path)
+      mtime = File.mtime(path) if File.exist?(path)
+      
+      cached = @cache_mutex.synchronize do
+        cache_entry = @ast_cache[cache_key]
+        if cache_entry && cache_entry[:mtime] == mtime
+
+          # Update access time for LRU tracking
+          cache_entry[:accessed_at] = Time.now
+          cache_entry[:ast_nodes]
+        else
+          nil
+        end
+      end
+
+      if cached
+
+        # Use cached AST. Normalize through extract_schema_nodes so the new Simulyra
+        # (ProgramNode) syntax works here too — load_string already does this; load_file
+        # used to blindly #map the raw parse result and broke on every v2 .dsl file.
+        extract_schema_nodes(cached).map do |node|
+          schema = node.to_schema
+          @schemas[schema.name] = schema
+          schema
+        end
+      else
+
+        # Parse and cache
+        content = File.read(path)
+        parser = Parser::Parser.new
+        ast_nodes = parser.parse(content)
+
+
+        # Cache the AST with LRU eviction
+        @cache_mutex.synchronize do
+
+          # Limit cache size using LRU (Least Recently Used) eviction
+          if @ast_cache.size >= @max_cache_size
+
+            # Remove least recently used entry
+            oldest_key = @ast_cache.min_by { |_, v| v[:accessed_at] || Time.at(0) }[0]
+            @ast_cache.delete(oldest_key)
+          end
+          @ast_cache[cache_key] = { ast_nodes: ast_nodes, mtime: mtime, accessed_at: Time.now }
+        end
+
+        extract_schema_nodes(ast_nodes).map do |node|
+          schema = node.to_schema
+          @schemas[schema.name] = schema
+          schema
+        end
+      end
+    end
+
+    public
+
+
+    # Load schemas from all DSL files in a directory
+    #
+    # Loads and parses all .dsl files in the specified directory, adding
+    # all schemas defined in them to the registry. Existing schemas with
+    # the same name will be overwritten.
+    #
+    # @param dir [String] directory path containing .dsl files
+    # @param validate [Boolean] whether to validate copy() paths (default: config setting)
+    # @return [Array<Schema>] all schemas that were loaded
+    # @raise [Errno::ENOENT] if the directory doesn't exist
+    # @raise [Errors::ParseError] if any DSL file has syntax errors
+    # @raise [Errors::PathError] if copy() path validation fails
+    #
+    # @example
+    #   registry.load_dir("schemas/")
+    #   # => [#<Schema User>, #<Schema Order>, #<Schema Product>]
+    #
+    # @example Handle errors
+    #   begin
+    #     registry.load_dir("nonexistent/")
+    #   rescue Errno::ENOENT => e
+    #     puts "Directory not found: #{e.message}"
+    #   end
+    #
+    # @example Skip validation
+    #   registry.load_dir("schemas/", validate: false)
+    #
+
+    def load_dir(dir, validate: Synthra.configuration.validate_paths_on_load)
+      schemas = @mutex.synchronize do
+
+        # Validate and expand directory path
+        dir = File.expand_path(dir)
+        raise Errno::ENOENT, dir unless Dir.exist?(dir)
+
+
+        # Find all .dsl files
+        pattern = File.join(dir, "*.dsl")
+        files = Dir.glob(pattern)
+
+
+        # Load each file
+        all_schemas = []
+        files.each do |file|
+          # Call load_file_unsafe to avoid double synchronization (we're already in @mutex)
+          all_schemas.concat(load_file_unsafe(file))
+        end
+
+        all_schemas
+      end
+
+      # Validate paths outside mutex to avoid deadlock
+      validate_paths! if validate
+
+      schemas
+    end
+
+
+    # Load schemas from a DSL string
+    #
+    # Parses the DSL source code and adds all schemas to the registry.
+    # Useful for testing or when DSL content is dynamically generated.
+    #
+    # @param source [String] DSL source code
+    # @param validate [Boolean] whether to validate copy() paths (default: config setting)
+    # @return [Array<Schema>] the schemas that were parsed
+    # @raise [Errors::ParseError] if the DSL syntax is invalid
+    # @raise [Errors::PathError] if copy() path validation fails
+    #
+    # @example
+    #   dsl = <<~DSL
+    #     User:
+    #       id: uuid
+    #       name: name
+    #   DSL
+    #   
+    #   schemas = registry.load_string(dsl)
+    #   schemas.first.name  # => "User"
+    #
+    # @example Skip validation
+    #   schemas = registry.load_string(dsl, validate: false)
+    #
+
+    def load_string(source, validate: Synthra.configuration.validate_paths_on_load)
+      schemas = @mutex.synchronize do
+        parser = Parser::Parser.new
+        parse_result = parser.parse(source)
+
+        # Handle both legacy (array of SchemaNode) and Simulyra (ProgramNode) syntax
+        ast_nodes = extract_schema_nodes(parse_result)
+
+        ast_nodes.map do |node|
+          schema = node.to_schema
+          @schemas[schema.name] = schema
+          schema
+        end
+      end
+
+      # Validate paths outside mutex to avoid deadlock
+      validate_paths! if validate
+
+      schemas
+    end
+
+    private
+
+    # Extract schema nodes from parse result
+    # Handles both legacy (Array) and Simulyra (ProgramNode) syntax
+    #
+    # @param parse_result [Array, ProgramNode] parsed result
+    # @return [Array<SchemaNode>] array of schema nodes
+    #
+    def extract_schema_nodes(parse_result)
+      if parse_result.is_a?(Parser::AST::ProgramNode)
+        # Simulyra DSL syntax - combine all schemas
+        all_schemas = []
+        all_schemas.concat(parse_result.schemas) if parse_result.schemas
+        all_schemas.concat(parse_result.legacy_schemas) if parse_result.legacy_schemas
+        all_schemas
+      elsif parse_result.is_a?(Array)
+        # Legacy syntax - already an array of schema nodes
+        parse_result
+      else
+        # Single node - wrap in array
+        [parse_result].compact
+      end
+    end
+
+    public
+
+
+    # Get a schema by name
+    #
+    # Retrieves a schema from the registry. Raises KeyError if not found.
+    #
+    # @param name [String, Symbol] schema name
+    # @return [Schema] the schema
+    # @raise [KeyError] if schema is not found
+    #
+    # @example
+    #   user_schema = registry.schema("User")
+    #   user_schema.fields.length  # => 5
+    #
+    # @example Handle missing schema
+    #   begin
+    #     registry.schema("NonExistent")
+    #   rescue KeyError => e
+    #     puts e.message  # => "Schema not found: NonExistent"
+    #   end
+    #
+
+    def schema(name)
+      @mutex.synchronize do
+        @schemas.fetch(name.to_s) do
+          raise KeyError, "Schema not found: #{name}"
+        end
+      end
+    end
+
+    # Register an already-built Schema object under a name.
+    #
+    # Counterpart to load_string/load_file for callers that construct a Schema directly (OpenAPI
+    # import, ActiveRecord inference, the CLI/API server). Was referenced in those paths but never
+    # defined, so every one of them raised NoMethodError.
+    #
+    # @param name [String, Symbol] the schema name
+    # @param schema [Schema] the schema to register
+    # @return [Schema] the registered schema
+    #
+    def register_schema(name, schema)
+      @mutex.synchronize do
+        @schemas[name.to_s] = schema
+      end
+    end
+
+
+    # Get all registered schemas as a hash
+    #
+    # Returns a copy of the internal schemas hash to prevent modification.
+    #
+    # @return [Hash<String, Schema>] schema name => Schema mapping
+    #
+    # @example
+    #   all_schemas = registry.schemas
+    #   all_schemas.keys  # => ["User", "Order"]
+    #
+
+    def schemas
+      @mutex.synchronize do
+        @schemas.dup
+      end
+    end
+
+
+    # Check if a schema exists
+    #
+    # @param name [String, Symbol] schema name to check
+    # @return [Boolean] true if the schema exists
+    #
+    # @example
+    #   registry.schema?("User")    # => true
+    #   registry.schema?("Unknown") # => false
+    #
+
+    def schema?(name)
+      @mutex.synchronize do
+        @schemas.key?(name.to_s)
+      end
+    end
+
+
+    # Unregister a schema by name
+    #
+    # Removes a single schema from the registry.
+    #
+    # @param name [String] schema name to remove
+    # @return [Schema, nil] the removed schema, or nil if not found
+    #
+    # @example
+    #   registry.unregister("User")
+    #
+    def unregister(name)
+      @mutex.synchronize do
+        @schemas.delete(name.to_s)
+      end
+    end
+
+
+    # Clear all registered schemas
+    #
+    # Removes all schemas from the registry.
+    #
+    # @return [void]
+    #
+    # @example
+    #   registry.clear
+    #   registry.size  # => 0
+    #
+
+    def clear
+      @mutex.synchronize do
+        @schemas.clear
+        @cache_mutex.synchronize do
+          @ast_cache.clear
+        end
+      end
+    end
+
+
+    # Get the number of registered schemas
+    #
+    # @return [Integer] number of schemas in the registry
+    #
+    # @example
+    #   registry.load_file("user.dsl")
+    #   registry.size  # => 1
+    #
+
+    def size
+      @mutex.synchronize do
+        @schemas.size
+      end
+    end
+
+
+    # Alias for size
+    # @return [Integer]
+    alias count size
+
+
+    # Alias for size
+    # @return [Integer]
+    alias length size
+
+
+    # Iterate over all schemas
+    #
+    # Yields each schema name and schema object to the block.
+    #
+    # @yield [name, schema] block to execute for each schema
+    # @yieldparam name [String] the schema name
+    # @yieldparam schema [Schema] the schema object
+    # @return [Enumerator, void] returns Enumerator if no block given
+    #
+    # @example
+    #   registry.each do |name, schema|
+    #     puts "#{name}: #{schema.fields.length} fields"
+    #   end
+    #
+    # @example Get as array
+    #   pairs = registry.each.to_a
+    #   # => [["User", #<Schema>], ["Order", #<Schema>]]
+    #
+
+    def each(&block)
+      @mutex.synchronize do
+        @schemas.each(&block)
+      end
+    end
+
+
+    # Get all schema names
+    #
+    # @return [Array<String>] list of schema names
+    #
+    # @example
+    #   registry.names  # => ["User", "Order", "Product"]
+    #
+
+    def names
+      @mutex.synchronize do
+        @schemas.keys
+      end
+    end
+
+
+    # Validate all copy() paths in the registry
+    #
+    # Checks that all copy() type references point to valid paths
+    # in the schema structure. This catches typos and invalid
+    # references at load time rather than at generation time.
+    #
+    # @return [Array<Errors::PathError>] list of validation errors (empty if valid)
+    #
+    # @example
+    #   errors = registry.validate_paths
+    #   errors.each { |e| puts e.message }
+    #
+
+    def validate_paths
+      # Don't hold mutex during validation - the validator caches schemas
+      # to avoid deadlock
+      validator = Validator::PathValidator.new(self)
+      validator.validate
+    end
+
+
+    # Validate all copy() paths, raising on first error
+    #
+    # @raise [Errors::PathError] if any invalid path is found
+    # @return [true] if all paths are valid
+    #
+    # @example
+    #   registry.load_file("schema.dsl")
+    #   registry.validate_paths!  # Raises if copy() paths are invalid
+    #
+
+    def validate_paths!
+      # Don't hold mutex during validation - the validator caches schemas
+      # to avoid deadlock
+      validator = Validator::PathValidator.new(self)
+      validator.validate!
+    end
+  end
+end

data/lib/synthra/relationships.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Synthra
+  # Data Relationships Support
+  #
+  # Provides expressive relationship types for schemas:
+  # - belongs_to(Schema) - Required reference
+  # - has_one(Schema) - Optional single reference
+  # - has_many(Schema, count) - Collection reference
+  #
+  # @example DSL syntax
+  #   Order:
+  #     id: uuid
+  #     user: belongs_to(User)
+  #     items: has_many(OrderItem, 1..10)
+  #     shipping_address?: has_one(Address)
+  #
+  module Relationships
+    # Relationship type definitions
+    TYPES = {
+      belongs_to: { required: true, cardinality: :one },
+      has_one: { required: false, cardinality: :one },
+      has_many: { required: true, cardinality: :many }
+    }.freeze
+
+    # Parse a relationship type from DSL
+    #
+    # @param type_str [String] e.g., "belongs_to(User)"
+    # @return [Hash, nil] parsed relationship or nil if not a relationship
+    #
+    def self.parse(type_str)
+      return nil unless type_str.is_a?(String)
+
+      TYPES.keys.each do |rel_type|
+        pattern = /^#{rel_type}\((\w+)(?:,\s*(\d+)\.\.(\d+))?\)$/
+        if (match = type_str.match(pattern))
+          return {
+            type: rel_type,
+            target_schema: match[1],
+            min_count: match[2]&.to_i || 1,
+            max_count: match[3]&.to_i || 1,
+            **TYPES[rel_type]
+          }
+        end
+      end
+
+      nil
+    end
+
+    # Check if a type string is a relationship
+    #
+    # @param type_str [String]
+    # @return [Boolean]
+    #
+    def self.relationship?(type_str)
+      return false unless type_str.is_a?(String)
+      TYPES.keys.any? { |t| type_str.start_with?("#{t}(") }
+    end
+
+    # Convert relationship to standard Synthra type
+    #
+    # @param relationship [Hash] parsed relationship
+    # @return [String] equivalent standard type
+    #
+    def self.to_standard_type(relationship)
+      case relationship[:cardinality]
+      when :one
+        relationship[:target_schema]
+      when :many
+        "array(#{relationship[:target_schema]}, #{relationship[:min_count]}..#{relationship[:max_count]})"
+      end
+    end
+  end
+
+  module Types
+    module Core
+      # BelongsTo type - required single reference
+      class BelongsTo < Base
+        def generate_random(rng, context, args)
+          target_schema = args[:schema] || args[:target]
+          return nil unless target_schema
+
+          if context.registry&.schema?(target_schema)
+            referenced_schema = context.registry.schema(target_schema)
+            id_field = referenced_schema.field("id")
+            if id_field
+              # Generate just the ID
+              Generator::Engine.new(referenced_schema, registry: context.registry)
+                .generate(mode: :random)["id"]
+            end
+          else
+            # Fallback: generate a UUID
+            SecureRandom.uuid
+          end
+        end
+
+        def generate_edge(rng, context, args)
+          generate_random(rng, context, args)
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([nil, "", "invalid_id", 0, -1])
+        end
+
+        def generate_hostile(rng, context, args)
+          rng.sample([
+            "' OR '1'='1",
+            "1; DROP TABLE users;--",
+            "../../../etc/passwd",
+            "<script>alert(1)</script>"
+          ])
+        end
+      end
+
+      # HasOne type - optional single reference (generates full object)
+      class HasOne < Base
+        def generate_random(rng, context, args)
+          target_schema = args[:schema] || args[:target]
+          return nil unless target_schema
+
+          if context.registry&.schema?(target_schema)
+            referenced_schema = context.registry.schema(target_schema)
+            referenced_schema.generate(registry: context.registry, mode: :random)
+          end
+        end
+
+        def generate_edge(rng, context, args)
+          # Edge case: nil or empty
+          rng.boolean(0.5) ? nil : generate_random(rng, context, args)
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([nil, {}, [], "not_an_object"])
+        end
+
+        def generate_hostile(rng, context, args)
+          { "injection" => "' OR '1'='1" }
+        end
+      end
+
+      # HasMany type - collection reference
+      class HasMany < Base
+        def generate_random(rng, context, args)
+          target_schema = args[:schema] || args[:target]
+          min_count = args[:min] || 1
+          max_count = args[:max] || 5
+          count = rng.int(min_count, max_count)
+
+          return [] unless target_schema
+
+          if context.registry&.schema?(target_schema)
+            referenced_schema = context.registry.schema(target_schema)
+            count.times.map do
+              referenced_schema.generate(registry: context.registry, mode: :random)
+            end
+          else
+            []
+          end
+        end
+
+        def generate_edge(rng, context, args)
+          # Edge cases: empty array, single item, max items
+          edge_counts = [0, 1, args[:max] || 10]
+          count = rng.sample(edge_counts)
+          
+          target_schema = args[:schema] || args[:target]
+          return [] unless target_schema && count > 0
+
+          if context.registry&.schema?(target_schema)
+            referenced_schema = context.registry.schema(target_schema)
+            count.times.map do
+              referenced_schema.generate(registry: context.registry, mode: :edge)
+            end
+          else
+            []
+          end
+        end
+
+        def generate_invalid(rng, context, args)
+          rng.sample([nil, "not_an_array", {}, [nil, nil]])
+        end
+
+        def generate_hostile(rng, context, args)
+          # Generate array with hostile payloads
+          [
+            { "xss" => "<script>alert(1)</script>" },
+            { "sqli" => "'; DROP TABLE users;--" }
+          ]
+        end
+      end
+    end
+  end
+end