synthra 0.1.0

data/lib/synthra/quality_metrics.rb

@@ -0,0 +1,405 @@
+# frozen_string_literal: true
+
+module Synthra
+  # Data Quality Metrics
+  #
+  # Analyze generated data for quality, realism, and distribution.
+  # Useful for validating test data quality and debugging generation issues.
+  #
+  # @example Analyze generated data
+  #   records = Synthra.generate_many("User", 1000)
+  #   report = Synthra::QualityMetrics.analyze(records, schema: "User")
+  #
+  #   report.uniqueness[:email]  # => 100.0
+  #   report.distribution[:role] # => { "admin" => 5, "user" => 95 }
+  #   report.realism_score       # => 94.5
+  #
+  module QualityMetrics
+    class << self
+      # Analyze a collection of records
+      #
+      # @param records [Array<Hash>] generated records
+      # @param schema [String, Schema] schema for context
+      # @return [QualityReport] analysis report
+      #
+      def analyze(records, schema: nil)
+        schema = Synthra.registry.schema(schema.to_s) if schema.is_a?(String)
+
+        analyzer = Analyzer.new(records, schema)
+        analyzer.analyze
+      end
+
+      # Generate data with quality report
+      #
+      # @param schema_name [String] schema name
+      # @param count [Integer] number of records
+      # @param options [Hash] generation options
+      # @return [GenerationResult] records with quality report
+      #
+      def generate_with_quality(schema_name, count: 100, **options)
+        schema = Synthra.registry.schema(schema_name)
+        records = schema.generate_many(count, **options)
+        report = analyze(records, schema: schema)
+
+        GenerationResult.new(records, report)
+      end
+    end
+
+    # Data quality analyzer
+    class Analyzer
+      def initialize(records, schema = nil)
+        @records = records
+        @schema = schema
+        @field_names = detect_field_names
+      end
+
+      def analyze
+        QualityReport.new(
+          total_records: @records.length,
+          uniqueness: calculate_uniqueness,
+          distribution: calculate_distribution,
+          completeness: calculate_completeness,
+          type_consistency: calculate_type_consistency,
+          realism_score: calculate_realism_score,
+          patterns: detect_patterns,
+          anomalies: detect_anomalies
+        )
+      end
+
+      private
+
+      def detect_field_names
+        return @schema.fields.map(&:name) if @schema
+
+        @records.first&.keys || []
+      end
+
+      def calculate_uniqueness
+        result = {}
+
+        @field_names.each do |field|
+          values = @records.map { |r| r[field] }.compact
+          next if values.empty?
+
+          unique_count = values.uniq.length
+          total_count = values.length
+          result[field] = (unique_count.to_f / total_count * 100).round(2)
+        end
+
+        result
+      end
+
+      def calculate_distribution
+        result = {}
+
+        @field_names.each do |field|
+          values = @records.map { |r| r[field] }.compact
+
+          # Only calculate distribution for fields with limited cardinality
+          unique_values = values.uniq
+          next if unique_values.length > 50 || unique_values.length == values.length
+
+          distribution = values.tally.transform_values do |count|
+            (count.to_f / values.length * 100).round(2)
+          end
+
+          result[field] = distribution
+        end
+
+        result
+      end
+
+      def calculate_completeness
+        total_fields = @records.length * @field_names.length
+        return 100.0 if total_fields.zero?
+
+        filled_fields = @records.sum do |record|
+          @field_names.count { |f| !record[f].nil? && record[f] != "" }
+        end
+
+        (filled_fields.to_f / total_fields * 100).round(2)
+      end
+
+      def calculate_type_consistency
+        result = {}
+
+        @field_names.each do |field|
+          values = @records.map { |r| r[field] }.compact
+          next if values.empty?
+
+          types = values.map { |v| classify_type(v) }
+          type_counts = types.tally
+
+          # Consistency = % of most common type
+          most_common_count = type_counts.values.max
+          result[field] = (most_common_count.to_f / types.length * 100).round(2)
+        end
+
+        result
+      end
+
+      def calculate_realism_score
+        scores = []
+
+        # Score based on uniqueness of ID fields
+        id_fields = @field_names.select { |f| f.match?(/\A(id|uuid|_id)\z/i) }
+        id_fields.each do |field|
+          uniqueness = calculate_uniqueness[field] || 0
+          scores << uniqueness
+        end
+
+        # Score based on email format
+        email_fields = @field_names.select { |f| f.match?(/email/i) }
+        email_fields.each do |field|
+          values = @records.map { |r| r[field] }.compact
+          valid_emails = values.count { |v| v.to_s.match?(/@.*\./) }
+          scores << (valid_emails.to_f / values.length * 100) if values.any?
+        end
+
+        # Score based on completeness
+        scores << calculate_completeness
+
+        # Score based on type consistency
+        type_scores = calculate_type_consistency.values
+        scores << (type_scores.sum / type_scores.length) if type_scores.any?
+
+        # :nocov: unreachable in practice — completeness above always appends one score, so `scores`
+        # is never empty; kept as a defensive guard against future refactors.
+        return 0.0 if scores.empty?
+        # :nocov:
+
+        (scores.sum / scores.length).round(2)
+      end
+
+      def detect_patterns
+        patterns = {}
+
+        @field_names.each do |field|
+          values = @records.map { |r| r[field] }.compact
+          next if values.empty?
+
+          string_values = values.select { |v| v.is_a?(String) }
+          next if string_values.length < 10
+
+          # Detect length patterns
+          lengths = string_values.map(&:length)
+          patterns[field] = {
+            min_length: lengths.min,
+            max_length: lengths.max,
+            avg_length: (lengths.sum.to_f / lengths.length).round(2),
+            common_prefixes: find_common_prefixes(string_values),
+            common_suffixes: find_common_suffixes(string_values)
+          }
+        end
+
+        patterns
+      end
+
+      def detect_anomalies
+        anomalies = []
+
+        # Check for unexpected null ratios
+        @field_names.each do |field|
+          values = @records.map { |r| r[field] }
+          null_ratio = values.count(&:nil?).to_f / values.length
+
+          if null_ratio > 0.5
+            anomalies << {
+              type: :high_null_ratio,
+              field: field,
+              ratio: (null_ratio * 100).round(2)
+            }
+          end
+        end
+
+        # Check for duplicate IDs
+        id_fields = @field_names.select { |f| f.match?(/\A(id|uuid|_id)\z/i) }
+        id_fields.each do |field|
+          values = @records.map { |r| r[field] }.compact
+          duplicates = values.length - values.uniq.length
+
+          if duplicates > 0
+            anomalies << {
+              type: :duplicate_ids,
+              field: field,
+              count: duplicates
+            }
+          end
+        end
+
+        # Check for unrealistic distributions
+        calculate_distribution.each do |field, dist|
+          max_percentage = dist.values.max || 0
+          if max_percentage > 90
+            anomalies << {
+              type: :skewed_distribution,
+              field: field,
+              dominant_value: dist.key(max_percentage),
+              percentage: max_percentage
+            }
+          end
+        end
+
+        anomalies
+      end
+
+      def classify_type(value)
+        case value
+        when nil then :null
+        when Integer then :integer
+        when Float then :float
+        when TrueClass, FalseClass then :boolean
+        when Array then :array
+        when Hash then :object
+        when String
+          if value.match?(/\A\d{4}-\d{2}-\d{2}/)
+            :datetime
+          elsif value.match?(/\A[0-9a-f-]{36}\z/i)
+            :uuid
+          else
+            :string
+          end
+        else
+          :unknown
+        end
+      end
+
+      def find_common_prefixes(strings, min_length: 2)
+        return [] if strings.length < 10
+
+        prefixes = Hash.new(0)
+        strings.each do |s|
+          (min_length..[s.length, 10].min).each do |len|
+            prefixes[s[0, len]] += 1
+          end
+        end
+
+        prefixes.select { |_, count| count > strings.length * 0.1 }
+                .sort_by { |_, count| -count }
+                .first(3)
+                .map(&:first)
+      end
+
+      def find_common_suffixes(strings, min_length: 2)
+        return [] if strings.length < 10
+
+        suffixes = Hash.new(0)
+        strings.each do |s|
+          (min_length..[s.length, 10].min).each do |len|
+            suffixes[s[-len..]] += 1
+          end
+        end
+
+        suffixes.select { |_, count| count > strings.length * 0.1 }
+                .sort_by { |_, count| -count }
+                .first(3)
+                .map(&:first)
+      end
+    end
+
+    # Quality analysis report
+    class QualityReport
+      attr_reader :total_records, :uniqueness, :distribution, :completeness
+      attr_reader :type_consistency, :realism_score, :patterns, :anomalies
+
+      def initialize(**attributes)
+        @total_records = attributes[:total_records]
+        @uniqueness = attributes[:uniqueness]
+        @distribution = attributes[:distribution]
+        @completeness = attributes[:completeness]
+        @type_consistency = attributes[:type_consistency]
+        @realism_score = attributes[:realism_score]
+        @patterns = attributes[:patterns]
+        @anomalies = attributes[:anomalies]
+      end
+
+      # Check if data passes quality threshold
+      #
+      # @param threshold [Float] minimum realism score (0-100)
+      # @return [Boolean]
+      #
+      def passes?(threshold: 80)
+        realism_score >= threshold && anomalies.empty?
+      end
+
+      # Get a summary string
+      #
+      # @return [String]
+      #
+      def summary
+        lines = [
+          "Quality Report (#{total_records} records)",
+          "=" * 40,
+          "Realism Score: #{realism_score}%",
+          "Completeness: #{completeness}%",
+          "",
+          "Uniqueness:",
+          *uniqueness.map { |f, u| "  #{f}: #{u}%" },
+          ""
+        ]
+
+        if anomalies.any?
+          lines << "Anomalies:"
+          anomalies.each do |a|
+            lines << "  ⚠️  #{a[:type]} in #{a[:field]}"
+          end
+        else
+          lines << "✅ No anomalies detected"
+        end
+
+        lines.join("\n")
+      end
+
+      # Convert to hash
+      def to_h
+        {
+          total_records: total_records,
+          uniqueness: uniqueness,
+          distribution: distribution,
+          completeness: completeness,
+          type_consistency: type_consistency,
+          realism_score: realism_score,
+          patterns: patterns,
+          anomalies: anomalies
+        }
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+
+    # Result with both records and quality report
+    class GenerationResult
+      attr_reader :records, :quality_report
+
+      def initialize(records, quality_report)
+        @records = records
+        @quality_report = quality_report
+      end
+
+      # Delegate array methods to records
+      def each(&block)
+        @records.each(&block)
+      end
+
+      def map(&block)
+        @records.map(&block)
+      end
+
+      def length
+        @records.length
+      end
+
+      alias size length
+
+      def [](index)
+        @records[index]
+      end
+
+      def to_a
+        @records
+      end
+    end
+  end
+end

data/lib/synthra/rails_test_helper.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module Synthra
+  # Rails Test Helper Integration
+  #
+  # Provides seamless integration with Rails tests, allowing you to generate
+  # test data directly from ActiveRecord models or Synthra schemas.
+  #
+  # @example Setup in test_helper.rb
+  #   require 'synthra/rails_test_helper'
+  #   Synthra.configure_test_helper!
+  #
+  #   class ActiveSupport::TestCase
+  #     include Synthra::RailsTestHelper
+  #   end
+  #
+  # @example Usage in tests
+  #   class UserTest < ActiveSupport::TestCase
+  #     test "validates email format" do
+  #       user = generate_for_test(User)
+  #       assert user.valid?
+  #     end
+  #   end
+  #
+  module RailsTestHelper
+    # Generate test data for a model or schema
+    #
+    # @param model_or_schema [Class, String, Schema] ActiveRecord model, schema name, or Schema
+    # @param mode [Symbol] generation mode (:valid, :invalid, :edge, :random)
+    # @param traits [Array<Symbol>] traits to apply
+    # @param overrides [Hash] field overrides
+    # @return [Object] generated model instance or hash
+    #
+    # @example Generate valid user
+    #   user = generate_for_test(User)
+    #
+    # @example Generate with mode
+    #   user = generate_for_test(User, :invalid)
+    #
+    # @example With overrides
+    #   user = generate_for_test(User, :valid, email: "test@example.com")
+    #
+    def generate_for_test(model_or_schema, mode = :valid, **overrides)
+      schema = resolve_schema(model_or_schema)
+      generation_mode = mode == :valid ? :random : mode
+      
+      data = schema.generate(mode: generation_mode, overrides: overrides)
+      
+      if model_or_schema.is_a?(Class) && defined?(ActiveRecord) && model_or_schema < ActiveRecord::Base
+        model_or_schema.new(filter_attributes(model_or_schema, data))
+      else
+        data
+      end
+    end
+
+    # Generate and persist test data
+    #
+    # @param model [Class] ActiveRecord model class
+    # @param mode [Symbol] generation mode
+    # @param overrides [Hash] field overrides
+    # @return [Object] persisted model instance
+    #
+    # @example Create user in database
+    #   user = create_for_test(User)
+    #   assert user.persisted?
+    #
+    def create_for_test(model, mode = :valid, **overrides)
+      record = generate_for_test(model, mode, **overrides)
+      record.save! if record.respond_to?(:save!)
+      record
+    end
+
+    # Generate multiple test records
+    #
+    # @param model_or_schema [Class, String, Schema] model or schema
+    # @param count [Integer] number of records
+    # @param mode [Symbol] generation mode
+    # @param overrides [Hash] field overrides
+    # @return [Array] array of generated records
+    #
+    # @example Generate 10 users
+    #   users = generate_many_for_test(User, 10)
+    #
+    def generate_many_for_test(model_or_schema, count, mode = :valid, **overrides)
+      count.times.map { generate_for_test(model_or_schema, mode, **overrides) }
+    end
+
+    # Generate and persist multiple test records
+    #
+    # @param model [Class] ActiveRecord model
+    # @param count [Integer] number of records
+    # @param mode [Symbol] generation mode
+    # @param overrides [Hash] field overrides
+    # @return [Array] array of persisted records
+    #
+    def create_many_for_test(model, count, mode = :valid, **overrides)
+      count.times.map { create_for_test(model, mode, **overrides) }
+    end
+
+    private
+
+    def resolve_schema(model_or_schema)
+      case model_or_schema
+      when Synthra::Schema
+        model_or_schema
+      when String, Symbol
+        Synthra.parse(Synthra::SchemaInference.infer_dsl(model_or_schema.to_s))
+      when Class
+        if defined?(ActiveRecord) && model_or_schema < ActiveRecord::Base
+          Synthra.parse(Synthra::SchemaInference.from_active_record(model_or_schema))
+        else
+          Synthra.parse(Synthra::SchemaInference.infer_dsl(model_or_schema.name))
+        end
+      else
+        raise ArgumentError, "Unknown model/schema type: #{model_or_schema.class}"
+      end
+    end
+
+    def filter_attributes(model, data)
+      return data unless defined?(ActiveRecord) && model < ActiveRecord::Base
+      
+      allowed = model.column_names
+      data.select { |k, _| allowed.include?(k.to_s) }
+    end
+  end
+
+  # Schema Inference from ActiveRecord models
+  #
+  # Automatically generates Synthra schemas from ActiveRecord models
+  # by inspecting column types, validations, and associations.
+  #
+  module SchemaInference
+    class << self
+      # Generate DSL from ActiveRecord model
+      #
+      # @param model [Class] ActiveRecord model class
+      # @return [String] DSL string
+      #
+      def from_active_record(model)
+        lines = ["#{model.name}:"]
+        
+        model.columns.each do |column|
+          next if skip_column?(column.name)
+          
+          type = infer_type_from_column(column, model)
+          optional = column.null ? "?" : ""
+          lines << "  #{column.name}#{optional}: #{type}"
+        end
+        
+        lines.join("\n")
+      end
+
+      # Generate minimal DSL from schema name
+      #
+      # @param name [String] schema name
+      # @return [String] DSL string
+      #
+      def infer_dsl(name)
+        <<~DSL
+          #{name}:
+            id: uuid
+        DSL
+      end
+
+      private
+
+      def skip_column?(name)
+        %w[id created_at updated_at].include?(name.to_s)
+      end
+
+      def infer_type_from_column(column, model)
+        # Check for specific patterns in column name
+        name = column.name.to_s
+        
+        return "email" if name.include?("email")
+        return "phone" if name.include?("phone")
+        return "url" if name.include?("url") || name.include?("link")
+        return "uuid" if name.end_with?("_id") || name == "uuid"
+        return "password" if name.include?("password")
+        return "name" if name == "name" || name.end_with?("_name")
+        return "address" if name.include?("address")
+        return "city" if name == "city"
+        return "state" if name == "state"
+        return "country" if name == "country"
+        return "postal_code" if name.include?("zip") || name.include?("postal")
+        
+        # Fall back to column type
+        case column.type
+        when :string, :text
+          infer_string_type(column, model)
+        when :integer, :bigint
+          "number"
+        when :float, :decimal
+          "money"
+        when :boolean
+          "boolean"
+        when :date
+          "date"
+        when :datetime, :timestamp
+          "timestamp"
+        when :uuid
+          "uuid"
+        when :json, :jsonb
+          "object"
+        else
+          "text"
+        end
+      end
+
+      def infer_string_type(column, model)
+        # Check for enum
+        if model.respond_to?(:defined_enums) && model.defined_enums.key?(column.name.to_s)
+          values = model.defined_enums[column.name.to_s].keys
+          return "enum(#{values.join(', ')})"
+        end
+        
+        # Check for length constraint
+        if column.limit && column.limit <= 50
+          "text(1..#{column.limit})"
+        else
+          "text"
+        end
+      end
+    end
+  end
+
+  class << self
+    # Configure Rails test helper
+    #
+    # @return [void]
+    #
+    def configure_test_helper!
+      return unless defined?(Rails)
+      
+      # Auto-load schemas from standard locations
+      schema_paths = [
+        Rails.root.join("schemas"),
+        Rails.root.join("test/schemas"),
+        Rails.root.join("spec/schemas")
+      ]
+      
+      @default_registry ||= Registry.new
+      schema_paths.each do |path|
+        @default_registry.load_dir(path.to_s) if path.exist?
+      end
+    end
+  end
+end