synthra 0.1.0

data/lib/synthra/validator/path_validator.rb

@@ -0,0 +1,615 @@
+# frozen_string_literal: true
+
+require "set"
+
+# =============================================================================
+
+# Synthra Path Validator
+# =============================================================================
+#
+# Validates copy() path references against schema structure at parse/load time.
+# This catches path typos and invalid references before data generation.
+#
+# @example Validate paths in a registry
+#   validator = PathValidator.new(registry)
+#   validator.validate!
+#
+# =============================================================================
+
+
+module Synthra
+  module Validator
+
+    # Validates copy() path references against schema structure
+    #
+    # The PathValidator scans all schemas in a registry for copy() type
+    # fields and validates that the referenced paths actually exist.
+    # It handles:
+    # - Direct field references (e.g., "user_id")
+    # - Nested field references (e.g., "address.city")
+    # - map_by_field alias references (e.g., "users.sender.id")
+    #
+    # @example Validate all paths in a registry
+    #   validator = PathValidator.new(registry)
+    #   validator.validate!  # Raises PathError if invalid paths found
+    #
+    # @example Get validation results without raising
+    #   errors = validator.validate
+    #   errors.each { |e| puts e.message }
+    #
+
+    class PathValidator
+      # @param registry [Registry] the registry containing schemas to validate
+      def initialize(registry)
+        @registry = registry
+        @path_index = {}
+        @copy_paths = []
+        # Cache schemas to avoid mutex deadlock when registry calls back
+        @schemas_cache = registry.schemas
+      end
+
+      # Validate all copy() paths in the registry
+      #
+      # @return [Array<PathError, CycleError>] list of validation errors (empty if valid)
+      #
+      def validate
+        build_path_index
+        collect_copy_paths
+
+        errors = []
+        errors.concat(validate_paths)
+        errors.concat(validate_field_order)
+        errors.concat(validate_ref_targets)
+        errors.concat(detect_cycles)
+        errors
+      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
+      #
+      def validate!
+        errors = validate
+        raise errors.first if errors.any?
+
+        true
+      end
+
+      private
+
+      # Build an index of all available field paths in all schemas
+      #
+      # @return [void]
+      #
+      def build_path_index
+        @path_index = {}
+
+        @schemas_cache.each do |name, schema|
+          # Track visited schemas per top-level schema to detect cycles
+          visited = Set.new
+          build_schema_paths(name, schema, "", visited)
+        end
+      end
+
+      # Build paths for a single schema
+      #
+      # @param name [String] schema name
+      # @param schema [Schema] the schema
+      # @param prefix [String] path prefix for nested fields
+      # @param visited [Set] schemas already visited in this path
+      # @return [void]
+      #
+      def build_schema_paths(name, schema, prefix, visited)
+        # Avoid infinite recursion on circular references
+        return if visited.include?(name)
+        visited.add(name)
+
+        schema.fields.each do |field|
+          field_path = prefix.empty? ? field.name : "#{prefix}.#{field.name}"
+          @path_index[field_path] = { schema: name, field: field }
+
+          # Handle nested schema types
+          if nested_schema?(field)
+            nested_name = field.type_name
+            if schema_exists?(nested_name) && !visited.include?(nested_name)
+              nested_schema = get_schema(nested_name)
+              build_schema_paths(nested_name, nested_schema, field_path, visited.dup)
+            end
+          end
+
+          # Handle map_by_field entries
+          if map_by_field?(field)
+            build_map_by_field_paths(field, field_path, visited)
+          end
+
+          # Handle array types with nested schemas
+          if array_with_nested_schema?(field)
+            element_type = field.type_args[:element]
+            if schema_exists?(element_type.to_s) && !visited.include?(element_type.to_s)
+              nested_schema = get_schema(element_type.to_s)
+              # Arrays can be accessed by index like "items.0.name"
+              build_schema_paths(element_type.to_s, nested_schema, "#{field_path}.0", visited.dup)
+            end
+          end
+        end
+      end
+
+      # Build paths for map_by_field entries
+      #
+      # @param field [Field] the map_by_field field
+      # @param prefix [String] path prefix
+      # @param visited [Set] schemas already visited in this path
+      # @return [void]
+      #
+      def build_map_by_field_paths(field, prefix, visited)
+        entries = field.type_args[:entries] || {}
+
+        entries.each do |entry_name, entry_info|
+          entry_path = "#{prefix}.#{entry_name}"
+          @path_index[entry_path] = { schema: nil, field: field, entry: entry_name }
+
+          # Get the schema name (handle both string and hash formats)
+          schema_name = if entry_info.is_a?(Hash)
+                          entry_info[:schema] || entry_info["schema"]
+                        else
+                          entry_info.to_s
+                        end
+
+          if schema_exists?(schema_name) && !visited.include?(schema_name)
+            nested_schema = get_schema(schema_name)
+            build_schema_paths(schema_name, nested_schema, entry_path, visited.dup)
+          end
+        end
+      end
+
+      # Collect all copy() paths from all schemas
+      #
+      # @return [void]
+      #
+      def collect_copy_paths
+        @copy_paths = []
+        @collected_schemas = Set.new
+
+        @schemas_cache.each do |name, schema|
+          collect_schema_copy_paths(name, schema)
+        end
+      end
+
+      # Collect copy() paths from a single schema
+      #
+      # @param name [String] schema name
+      # @param schema [Schema] the schema
+      # @return [void]
+      #
+      def collect_schema_copy_paths(name, schema)
+        # Avoid infinite recursion on circular references
+        return if @collected_schemas.include?(name)
+        @collected_schemas.add(name)
+
+        schema.fields.each do |field|
+          if copy_type?(field)
+            path = extract_copy_path(field)
+            @copy_paths << {
+              path: path,
+              schema: name,
+              field: field.name,
+              line: nil  # Line info not available on Field
+            } if path
+          end
+
+          # Also check nested schemas recursively
+          if nested_schema?(field)
+            nested_name = field.type_name
+            if schema_exists?(nested_name) && !@collected_schemas.include?(nested_name)
+              nested_schema = get_schema(nested_name)
+              collect_schema_copy_paths(nested_name, nested_schema)
+            end
+          end
+        end
+      end
+
+      # Validate all collected copy() paths
+      #
+      # @return [Array<PathError>] list of validation errors
+      #
+      def validate_paths
+        errors = []
+
+        @copy_paths.each do |path_info|
+          path = path_info[:path]
+
+          # Skip validation if path contains parent context indicators
+          # (these need runtime resolution)
+          next if path_needs_runtime_resolution?(path)
+
+          unless path_exists?(path)
+            suggestions = find_similar_paths(path)
+            errors << Errors::PathError.new(
+              path,
+              available_paths: @path_index.keys.first(20),
+              suggestions: suggestions,
+              line: path_info[:line]
+            )
+          end
+        end
+
+        # Also validate map_by_field key fields
+        errors.concat(validate_map_by_field_keys)
+
+        errors
+      end
+
+      # Validate that copy() fields don't reference later-defined fields
+      #
+      # copy() can only reference fields that are defined BEFORE it in the schema.
+      # This is because fields are generated in definition order, so referencing
+      # a later field would result in nil.
+      #
+      # @return [Array<Errors::FieldOrderError>] list of field order errors
+      #
+      def validate_field_order
+        errors = []
+
+        @schemas_cache.each do |schema_name, schema|
+          field_names = schema.fields.map(&:name)
+
+          schema.fields.each_with_index do |field, field_index|
+            next unless copy_type?(field)
+
+            copy_path = extract_copy_path(field)
+            next unless copy_path
+
+            # Get the root field name from the path (e.g., "users.sender.id" -> "users")
+            root_field = copy_path.split(".").first
+            next unless root_field
+
+            # Check if the root field is defined in this schema
+            root_index = field_names.index(root_field)
+            next unless root_index # Field is from parent context or nested schema
+
+            # If the copy references a field defined AFTER it, that's a problem
+            if root_index >= field_index
+              errors << Errors::FieldOrderError.new(
+                field_name: field.name,
+                copy_path: copy_path,
+                schema_name: schema_name,
+                suggestion: "Move '#{root_field}' field before '#{field.name}' in schema '#{schema_name}'"
+              )
+            end
+          end
+        end
+
+        errors
+      end
+
+      # Validate that Ref() targets exist and have the referenced field
+      #
+      # @return [Array<PathError>] list of validation errors
+      #
+      def validate_ref_targets
+        errors = []
+
+        @schemas_cache.each do |schema_name, schema|
+          schema.fields.each do |field|
+            next unless ref_type?(field)
+
+            ref_schema = field.type_args[:schema] || field.type_args["schema"]
+            ref_field = field.type_args[:field] || field.type_args["field"]
+
+            next unless ref_schema
+
+            # Check if referenced schema exists
+            unless schema_exists?(ref_schema)
+              similar = Utils::StringDistance.similar_strings(ref_schema, @schemas_cache.keys, max_distance: 2, limit: 3)
+              errors << Errors::PathError.new(
+                "Ref(#{ref_schema}.#{ref_field})",
+                suggestions: similar.map { |s| "Ref(#{s}.#{ref_field || 'id'})" },
+                line: nil
+              )
+              next
+            end
+
+            # Check if referenced field exists in target schema
+            if ref_field
+              target_schema = get_schema(ref_schema)
+              field_names = target_schema.fields.map(&:name)
+
+              unless field_names.include?(ref_field)
+                similar = Utils::StringDistance.similar_strings(ref_field, field_names, max_distance: 2, limit: 3)
+                errors << Errors::PathError.new(
+                  "#{ref_schema}.#{ref_field}",
+                  suggestions: similar.map { |f| "Ref(#{ref_schema}.#{f})" },
+                  line: nil
+                )
+              end
+            end
+          end
+        end
+
+        errors
+      end
+
+      # Validate that map_by_field key fields exist in referenced schemas
+      #
+      # @return [Array<PathError>] list of validation errors
+      #
+      def validate_map_by_field_keys
+        errors = []
+
+        @schemas_cache.each do |schema_name, schema|
+          schema.fields.each do |field|
+            next unless map_by_field?(field)
+
+            key_field = field.type_args[:key_field] || field.type_args["key_field"] || "id"
+            entries = field.type_args[:entries] || field.type_args["entries"] || {}
+
+            entries.each do |entry_name, entry_info|
+              # Get the schema name (handle both string and hash formats)
+              entry_schema_name = if entry_info.is_a?(Hash)
+                                     entry_info[:schema] || entry_info["schema"]
+                                   else
+                                     entry_info.to_s
+                                   end
+
+              next unless entry_schema_name && schema_exists?(entry_schema_name)
+
+              entry_schema = get_schema(entry_schema_name)
+              field_names = entry_schema.fields.map(&:name)
+
+              unless field_names.include?(key_field)
+                similar = Utils::StringDistance.similar_strings(key_field, field_names, max_distance: 2, limit: 3)
+                errors << Errors::PathError.new(
+                  "#{key_field}' in schema '#{entry_schema_name}",
+                  suggestions: similar.map { |f| "#{entry_schema_name}.#{f}" },
+                  line: nil
+                )
+              end
+            end
+          end
+        end
+
+        errors
+      end
+
+      # Check if a path exists in the index
+      #
+      # @param path [String] the path to check
+      # @return [Boolean] true if path exists
+      #
+      def path_exists?(path)
+        return true if @path_index.key?(path)
+
+        # Try partial path matching (for nested paths that may be dynamically generated)
+        parts = path.split(".")
+        current_path = ""
+
+        parts.each_with_index do |part, idx|
+          current_path = idx.zero? ? part : "#{current_path}.#{part}"
+
+          # Check if this is the last part
+          if idx == parts.length - 1
+            return @path_index.key?(current_path)
+          end
+
+          # If path doesn't exist and we're not at the end, check if we have a dynamic path
+          next if @path_index.key?(current_path)
+
+          # Check for array index patterns (e.g., "0" for first element)
+          return true if part =~ /^\d+$/
+
+          return false
+        end
+
+        false
+      end
+
+      # Check if a path needs runtime resolution
+      #
+      # @param path [String] the path to check
+      # @return [Boolean] true if path needs runtime resolution
+      #
+      def path_needs_runtime_resolution?(path)
+        # Paths with array indices may need runtime resolution
+        path =~ /\.\d+\./ || path.start_with?(".")
+      end
+
+      # Find paths similar to the given path
+      #
+      # @param path [String] the path to match
+      # @return [Array<String>] similar paths
+      #
+      def find_similar_paths(path)
+        Utils::StringDistance.similar_strings(path, @path_index.keys, max_distance: 3, limit: 3)
+      end
+
+      # Check if field is a copy() type
+      #
+      # @param field [Field] the field to check
+      # @return [Boolean] true if copy type
+      #
+      def copy_type?(field)
+        field.type_name == "copy"
+      end
+
+      # Extract the path argument from a copy() type
+      #
+      # @param field [Field] the copy field
+      # @return [String, nil] the path or nil
+      #
+      def extract_copy_path(field)
+        args = field.type_args
+        args[:path] || args["path"] || args.values.first
+      end
+
+      # Check if field is a nested schema type
+      #
+      # @param field [Field] the field to check
+      # @return [Boolean] true if nested schema
+      #
+      def nested_schema?(field)
+        type_name = field.type_name
+        return false unless type_name
+
+        # Not a builtin type and exists in registry
+        !Types::Registry.registered?(type_name) && schema_exists?(type_name)
+      end
+
+      # Check if field is a map_by_field type
+      #
+      # @param field [Field] the field to check
+      # @return [Boolean] true if map_by_field
+      #
+      def map_by_field?(field)
+        field.type_name == "map_by_field"
+      end
+
+      # Check if field is a Ref() type
+      #
+      # @param field [Field] the field to check
+      # @return [Boolean] true if Ref type
+      #
+      def ref_type?(field)
+        field.type_name == "reference" || field.type_name == "Ref"
+      end
+
+      # Check if field is an array with nested schema
+      #
+      # @param field [Field] the field to check
+      # @return [Boolean] true if array with schema element
+      #
+      def array_with_nested_schema?(field)
+        return false unless field.type_name == "array"
+
+        element_type = field.type_args[:element]
+        return false unless element_type
+
+        schema_exists?(element_type.to_s)
+      end
+
+      # Check if a schema exists (without mutex deadlock)
+      #
+      # @param name [String] schema name
+      # @return [Boolean] true if schema exists
+      #
+      def schema_exists?(name)
+        @schemas_cache.key?(name.to_s)
+      end
+
+      # Get a schema (without mutex deadlock)
+      #
+      # @param name [String] schema name
+      # @return [Schema] the schema
+      #
+      def get_schema(name)
+        @schemas_cache[name.to_s]
+      end
+
+      # Detect circular references in schema definitions
+      #
+      # @return [Array<CycleError>] list of cycle errors
+      #
+      def detect_cycles
+        errors = []
+        visited = {}
+        rec_stack = {}
+
+        @schemas_cache.each_key do |schema_name|
+          cycle = find_cycle(schema_name, visited, rec_stack, [])
+          errors << Errors::CycleError.new(cycle) if cycle
+        end
+
+        errors
+      end
+
+      # Find a cycle starting from the given schema
+      #
+      # @param name [String] schema name to start from
+      # @param visited [Hash] globally visited schemas
+      # @param rec_stack [Hash] current recursion stack
+      # @param path [Array<String>] current path through schemas
+      # @return [Array<String>, nil] cycle path if found, nil otherwise
+      #
+      def find_cycle(name, visited, rec_stack, path)
+        # Skip if already fully processed
+        return nil if visited[name]
+
+        # If we're back in the recursion stack, we found a cycle
+        if rec_stack[name]
+          cycle_start = path.index(name)
+          return path[cycle_start..] + [name]
+        end
+
+        # Skip if schema doesn't exist
+        return nil unless schema_exists?(name)
+
+        # Mark as being processed
+        rec_stack[name] = true
+        current_path = path + [name]
+
+        schema = get_schema(name)
+        return nil unless schema
+
+        # Check all referenced schemas
+        schema.fields.each do |field|
+          referenced_schemas = get_referenced_schemas(field)
+
+          referenced_schemas.each do |ref_name|
+            cycle = find_cycle(ref_name, visited, rec_stack, current_path)
+            return cycle if cycle
+          end
+        end
+
+        # Mark as fully processed
+        rec_stack[name] = false
+        visited[name] = true
+        nil
+      end
+
+      # Get all schemas referenced by a field
+      #
+      # @param field [Field] the field to check
+      # @return [Array<String>] list of referenced schema names
+      #
+      def get_referenced_schemas(field)
+        refs = []
+
+        # Direct schema reference
+        if nested_schema?(field)
+          refs << field.type_name
+        end
+
+        # Array element type
+        if array_with_nested_schema?(field)
+          element_type = field.type_args[:element]
+          refs << element_type.to_s if element_type
+        end
+
+        # map_by_field entries
+        if map_by_field?(field)
+          entries = field.type_args[:entries] || {}
+          entries.each do |_, entry_info|
+            schema_name = if entry_info.is_a?(Hash)
+                            entry_info[:schema] || entry_info["schema"]
+                          else
+                            entry_info.to_s
+                          end
+            refs << schema_name if schema_name
+          end
+        end
+
+        # one_of schemas
+        if field.type_name == "one_of"
+          schemas = field.type_args[:schemas] || []
+          schemas.each do |s|
+            schema_name = s.is_a?(Hash) ? (s[:schema] || s["schema"]) : s.to_s
+            refs << schema_name if schema_name
+          end
+        end
+
+        refs.select { |r| schema_exists?(r) }
+      end
+    end
+  end
+end
+

data/lib/synthra/version.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Version
+# =============================================================================
+#
+# This file defines the version constant for the Synthra gem.
+# The version follows Semantic Versioning (https://semver.org/):
+#
+# MAJOR.MINOR.PATCH
+#   - MAJOR: Incremented for incompatible API changes
+#   - MINOR: Incremented for backward-compatible functionality additions
+#   - PATCH: Incremented for backward-compatible bug fixes
+#
+# =============================================================================
+
+
+# :nocov:
+module Synthra
+
+  # Current version of the Synthra gem
+  #
+  # @return [String] the semantic version string
+  #
+  # @example Check version
+  #   puts Synthra::VERSION  # => "0.1.0"
+  #
+  # @example Compare versions
+  #   Gem::Version.new(Synthra::VERSION) >= Gem::Version.new("0.1.0")
+  #
+
+  VERSION = "0.1.0"
+end
+# :nocov: