synthra 0.1.0

data/lib/synthra/contracts_registry.rb

@@ -0,0 +1,408 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "digest"
+require "monitor" # reentrant lock: read methods can be called from within locked write methods
+
+module Synthra
+  # Data Contracts Registry
+  #
+  # Centralized registry for versioned schemas with:
+  # - Semantic versioning support
+  # - Publishing and deprecation
+  # - Compatibility checking
+  # - Change history tracking
+  #
+  # @example Publish a schema
+  #   registry = Synthra::ContractsRegistry.new("contracts/")
+  #   registry.publish("User", version: "1.0.0", schema: user_schema)
+  #
+  # @example Check compatibility
+  #   registry.compatible?("User", "1.0.0", "2.0.0")
+  #
+  class ContractsRegistry
+    attr_reader :base_dir, :contracts
+
+    # Contract states
+    STATES = %i[draft published deprecated retired].freeze
+
+    # Create a new contracts registry
+    #
+    # @param base_dir [String] directory for storing contracts
+    #
+    def initialize(base_dir = "contracts")
+      @base_dir = base_dir
+      @contracts = {}
+      # Monitor (reentrant): read methods now lock too, and the already-locked write methods call
+      # them — a plain Mutex would self-deadlock on that nesting.
+      @mutex = Monitor.new
+      
+      FileUtils.mkdir_p(@base_dir)
+      load_contracts
+    end
+
+    # Publish a new schema version
+    #
+    # @param name [String] schema name
+    # @param version [String] semantic version (e.g., "1.0.0")
+    # @param schema [Schema] the schema to publish
+    # @param changelog [String] optional changelog entry
+    # @return [Hash] published contract metadata
+    #
+    def publish(name, version:, schema:, changelog: nil)
+      @mutex.synchronize do
+        key = contract_key(name, version)
+        
+        # Validate version format
+        validate_version!(version)
+        
+        # Check if already published
+        if @contracts[key] && @contracts[key][:state] == :published
+          raise ContractError, "Contract #{key} is already published"
+        end
+        
+        # Create contract
+        contract = {
+          name: name,
+          version: version,
+          state: :published,
+          schema_hash: hash_schema(schema),
+          fields: schema.fields.map { |f| field_signature(f) },
+          behaviors: schema.behaviors,
+          published_at: Time.now.iso8601,
+          changelog: changelog,
+          dsl_content: schema.respond_to?(:dsl_content) ? schema.dsl_content : nil
+        }
+        
+        @contracts[key] = contract
+        save_contract(key, contract)
+        
+        # Record history
+        record_history(name, version, :published, changelog)
+        
+        contract
+      end
+    end
+
+    # Deprecate a schema version
+    #
+    # @param name [String] schema name
+    # @param version [String] version to deprecate
+    # @param sunset_date [Date] when the version will be retired
+    # @param message [String] deprecation message
+    #
+    def deprecate(name, version:, sunset_date: nil, message: nil)
+      @mutex.synchronize do
+        key = contract_key(name, version)
+        contract = @contracts[key]
+        
+        raise ContractError, "Contract #{key} not found" unless contract
+        
+        contract[:state] = :deprecated
+        contract[:deprecated_at] = Time.now.iso8601
+        contract[:sunset_date] = sunset_date&.iso8601
+        contract[:deprecation_message] = message
+        
+        save_contract(key, contract)
+        record_history(name, version, :deprecated, message)
+      end
+    end
+
+    # Retire a schema version (no longer available)
+    #
+    # @param name [String] schema name
+    # @param version [String] version to retire
+    #
+    def retire(name, version:)
+      @mutex.synchronize do
+        key = contract_key(name, version)
+        contract = @contracts[key]
+        
+        raise ContractError, "Contract #{key} not found" unless contract
+        
+        contract[:state] = :retired
+        contract[:retired_at] = Time.now.iso8601
+        
+        save_contract(key, contract)
+        record_history(name, version, :retired)
+      end
+    end
+
+    # Get a specific contract
+    #
+    # @param name [String] schema name
+    # @param version [String] version (nil for latest)
+    # @return [Hash, nil] contract or nil
+    #
+    def get(name, version: nil)
+      @mutex.synchronize do
+        if version
+          @contracts[contract_key(name, version)]
+        else
+          latest_version(name)
+        end
+      end
+    end
+
+    # Get the latest published version
+    #
+    # @param name [String] schema name
+    # @return [Hash, nil] latest contract or nil
+    #
+    def latest_version(name)
+      @mutex.synchronize do
+        versions = versions_for(name).select { |v| @contracts[contract_key(name, v)][:state] == :published }
+        next nil if versions.empty?
+
+        sorted = versions.sort_by { |v| Gem::Version.new(v) }
+        @contracts[contract_key(name, sorted.last)]
+      end
+    end
+
+    # Get all versions for a schema
+    #
+    # @param name [String] schema name
+    # @return [Array<String>] versions
+    #
+    def versions_for(name)
+      @mutex.synchronize do
+        @contracts.keys
+          .select { |k| k.start_with?("#{name}@") }
+          .map { |k| k.split("@").last }
+          .sort_by { |v| Gem::Version.new(v) rescue v }
+      end
+    end
+
+    # Check if two versions are compatible
+    #
+    # @param name [String] schema name
+    # @param old_version [String] old version
+    # @param new_version [String] new version
+    # @return [Hash] compatibility report
+    #
+    def compatible?(name, old_version, new_version)
+      @mutex.synchronize do
+        old_contract = @contracts[contract_key(name, old_version)]
+        new_contract = @contracts[contract_key(name, new_version)]
+
+        raise ContractError, "Contract #{name}@#{old_version} not found" unless old_contract
+        raise ContractError, "Contract #{name}@#{new_version} not found" unless new_contract
+
+        analyze_compatibility(old_contract, new_contract)
+      end
+    end
+
+    # List all contracts
+    #
+    # @param state [Symbol] filter by state (nil for all)
+    # @return [Array<Hash>] contracts
+    #
+    def list(state: nil)
+      @mutex.synchronize do
+        contracts = @contracts.values
+        contracts = contracts.select { |c| c[:state] == state } if state
+        contracts.sort_by { |c| [c[:name], Gem::Version.new(c[:version])] }
+      end
+    end
+
+    # List all unique schema names
+    #
+    # @return [Array<String>] schema names
+    #
+    def schema_names
+      @mutex.synchronize { @contracts.values.map { |c| c[:name] }.uniq.sort }
+    end
+
+    # Get change history for a schema
+    #
+    # @param name [String] schema name
+    # @return [Array<Hash>] history entries
+    #
+    def history(name)
+      @mutex.synchronize do
+        history_file = File.join(@base_dir, "history", "#{name}.json")
+        next [] unless File.exist?(history_file)
+
+        JSON.parse(File.read(history_file), symbolize_names: true)
+      end
+    end
+
+    # Validate a schema against a published contract
+    #
+    # @param name [String] schema name
+    # @param version [String] version
+    # @param schema [Schema] schema to validate
+    # @return [Hash] validation result
+    #
+    def validate(name, version:, schema:)
+      @mutex.synchronize do
+        contract = @contracts[contract_key(name, version)]
+        raise ContractError, "Contract #{name}@#{version} not found" unless contract
+
+        current_fields = schema.fields.map { |f| field_signature(f) }
+        contract_fields = contract[:fields]
+
+        {
+          valid: current_fields == contract_fields,
+          hash_match: hash_schema(schema) == contract[:schema_hash],
+          missing_fields: contract_fields - current_fields,
+          extra_fields: current_fields - contract_fields
+        }
+      end
+    end
+
+    # Export all contracts to a directory
+    #
+    # @param output_dir [String] output directory
+    #
+    def export(output_dir)
+      FileUtils.mkdir_p(output_dir)
+
+      @mutex.synchronize do
+        @contracts.each do |key, contract|
+          File.write(
+            File.join(output_dir, "#{key.gsub('@', '_v')}.json"),
+            JSON.pretty_generate(contract)
+          )
+        end
+      end
+    end
+
+    # Import contracts from a directory
+    #
+    # @param input_dir [String] input directory
+    #
+    def import(input_dir)
+      @mutex.synchronize do
+        Dir.glob(File.join(input_dir, "*.json")).each do |file|
+          contract = JSON.parse(File.read(file), symbolize_names: true)
+          key = contract_key(contract[:name], contract[:version])
+          @contracts[key] = contract
+          save_contract(key, contract)
+        end
+      end
+    end
+
+    private
+
+    def contract_key(name, version)
+      "#{name}@#{version}"
+    end
+
+    def validate_version!(version)
+      # \A..\z (not ^..$): ^/$ are line anchors in Ruby, so "1.0.0\n../../evil" would pass and then
+      # be used as a path fragment. \A..\z anchor the whole string and reject the embedded newline.
+      unless version.match?(/\A\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?\z/)
+        raise ContractError, "Invalid version format: #{version}. Use semantic versioning (e.g., 1.0.0)"
+      end
+    end
+
+    def hash_schema(schema)
+      content = schema.fields.map { |f| "#{f.name}:#{f.type_name}:#{f.optional?}:#{f.nullable?}" }.join("|")
+      Digest::SHA256.hexdigest(content)[0, 16]
+    end
+
+    def field_signature(field)
+      {
+        name: field.name,
+        type: field.type_name,
+        optional: field.optional?,
+        nullable: field.nullable?,
+        args_hash: Digest::MD5.hexdigest(field.type_args.to_s)[0, 8]
+      }
+    end
+
+    def load_contracts
+      contracts_dir = File.join(@base_dir, "schemas")
+      return unless Dir.exist?(contracts_dir)
+      
+      Dir.glob(File.join(contracts_dir, "*.json")).each do |file|
+        contract = JSON.parse(File.read(file), symbolize_names: true)
+        key = contract_key(contract[:name], contract[:version])
+        @contracts[key] = contract
+      end
+    end
+
+    def save_contract(key, contract)
+      contracts_dir = File.join(@base_dir, "schemas")
+      FileUtils.mkdir_p(contracts_dir)
+      
+      filename = key.gsub("@", "_v") + ".json"
+      File.write(File.join(contracts_dir, filename), JSON.pretty_generate(contract))
+    end
+
+    def record_history(name, version, action, message = nil)
+      history_dir = File.join(@base_dir, "history")
+      FileUtils.mkdir_p(history_dir)
+      
+      history_file = File.join(history_dir, "#{name}.json")
+      history = File.exist?(history_file) ? JSON.parse(File.read(history_file)) : []
+      
+      history << {
+        "version" => version,
+        "action" => action.to_s,
+        "message" => message,
+        "timestamp" => Time.now.iso8601
+      }
+      
+      File.write(history_file, JSON.pretty_generate(history))
+    end
+
+    def analyze_compatibility(old_contract, new_contract)
+      old_fields = old_contract[:fields].map { |f| f[:name] }
+      new_fields = new_contract[:fields].map { |f| f[:name] }
+      
+      removed = old_fields - new_fields
+      added = new_fields - old_fields
+      
+      # Check type changes
+      type_changes = []
+      (old_fields & new_fields).each do |name|
+        old_field = old_contract[:fields].find { |f| f[:name] == name }
+        new_field = new_contract[:fields].find { |f| f[:name] == name }
+        
+        if old_field[:type] != new_field[:type]
+          type_changes << { field: name, from: old_field[:type], to: new_field[:type] }
+        end
+      end
+      
+      # Check required changes
+      required_changes = []
+      (old_fields & new_fields).each do |name|
+        old_field = old_contract[:fields].find { |f| f[:name] == name }
+        new_field = new_contract[:fields].find { |f| f[:name] == name }
+        
+        if old_field[:optional] && !new_field[:optional]
+          required_changes << { field: name, change: "optional → required" }
+        end
+      end
+      
+      breaking = removed.any? || type_changes.any? || required_changes.any?
+      
+      {
+        compatible: !breaking,
+        breaking: breaking,
+        changes: {
+          removed_fields: removed,
+          added_fields: added,
+          type_changes: type_changes,
+          required_changes: required_changes
+        },
+        summary: generate_compatibility_summary(removed, added, type_changes, required_changes)
+      }
+    end
+
+    def generate_compatibility_summary(removed, added, type_changes, required_changes)
+      parts = []
+      parts << "Removed fields: #{removed.join(', ')}" if removed.any?
+      parts << "Added fields: #{added.join(', ')}" if added.any?
+      type_changes.each { |c| parts << "Type changed: #{c[:field]} (#{c[:from]} → #{c[:to]})" }
+      required_changes.each { |c| parts << "Required changed: #{c[:field]} (#{c[:change]})" }
+      parts.empty? ? "No changes" : parts.join("; ")
+    end
+  end
+
+  # Contract error
+  class ContractError < StandardError; end
+end

data/lib/synthra/database_seeder.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require "ostruct" # OpenStruct is used below; not a default gem on Ruby 3.5+/4.0, so require it.
+
+module Synthra
+  # Database Seeder with Foreign Key Awareness
+  #
+  # Intelligently seeds databases respecting foreign key constraints
+  # and relationships between tables.
+  #
+  # @example Basic usage
+  #   Synthra.seed_database do
+  #     create User, count: 100
+  #     create Order, count: 500      # Links to Users
+  #     create OrderItem, count: 2000 # Links to Orders
+  #   end
+  #
+  # @example With options
+  #   Synthra.seed_database(truncate: true) do
+  #     create User, count: 50, mode: :edge
+  #   end
+  #
+  class DatabaseSeeder
+    attr_reader :registry, :created_records, :options
+
+    # Create a new seeder
+    #
+    # @param registry [Registry] schema registry
+    # @param options [Hash] seeder options
+    # @option options [Boolean] :truncate Truncate tables before seeding
+    # @option options [Boolean] :disable_callbacks Disable ActiveRecord callbacks
+    # @option options [Integer] :batch_size Batch insert size (default: 1000)
+    #
+    def initialize(registry: nil, **options)
+      @registry = registry || Synthra.instance_variable_get(:@default_registry) || Registry.new
+      @options = {
+        truncate: false,
+        disable_callbacks: false,
+        batch_size: 1000
+      }.merge(options)
+      @created_records = Hash.new { |h, k| h[k] = [] }
+      @foreign_key_cache = {}
+    end
+
+    # Execute seeding with DSL
+    #
+    # @yield seeding DSL block
+    #
+    def seed(&block)
+      refuse_in_production!
+      setup_environment
+      instance_eval(&block)
+
+      summary
+    end
+
+    # Create records for a model
+    #
+    # @param model [Class] ActiveRecord model class
+    # @param count [Integer] number of records
+    # @param mode [Symbol] generation mode
+    # @param overrides [Hash] field overrides
+    #
+    def create(model, count:, mode: :random, **overrides)
+      schema_name = model.respond_to?(:name) ? model.name : model.to_s
+      schema = find_or_infer_schema(schema_name, model)
+
+      puts "Creating #{count} #{schema_name} records..."
+
+      records = []
+      count.times do
+        data = generate_with_fk_resolution(schema, model, mode, overrides)
+        records << data
+      end
+
+      # Batch insert for performance — also the path for disable_callbacks: insert_all skips AR
+      # callbacks at the DB layer per-model, so we never mutate the global ActiveRecord::Base chain.
+      if model.respond_to?(:insert_all) && (@options[:batch_size] > 1 || @options[:disable_callbacks])
+        insert_in_batches(model, records)
+      else
+        records.each do |data|
+          record = model.create!(data)
+          @created_records[schema_name] << record
+        end
+      end
+
+      puts "  ✓ Created #{count} #{schema_name} records"
+    end
+
+    # Create a single record and return it
+    #
+    # @param model [Class] ActiveRecord model
+    # @param mode [Symbol] generation mode
+    # @param overrides [Hash] field overrides
+    # @return [Object] created record
+    #
+    def create_one(model, mode: :random, **overrides)
+      schema_name = model.name
+      schema = find_or_infer_schema(schema_name, model)
+      
+      data = generate_with_fk_resolution(schema, model, mode, overrides)
+      record = model.create!(data)
+      @created_records[schema_name] << record
+      
+      record
+    end
+
+    # Get a random record from already created records
+    #
+    # @param model [Class] model class
+    # @return [Object, nil] random record or nil
+    #
+    def random_record(model)
+      records = @created_records[model.name]
+      records.sample if records.any?
+    end
+
+    # Get the ID of a random record
+    #
+    # @param model [Class] model class
+    # @return [Object, nil] random ID or nil
+    #
+    def random_id(model)
+      record = random_record(model)
+      record&.id
+    end
+
+    private
+
+    # SECURITY: the seeder truncates tables and (with disable_callbacks) flips
+    # ActiveRecord callbacks process-wide — catastrophic in production, especially
+    # multi-tenant where suppressed before_create callbacks (tenant scoping, audit)
+    # affect every concurrent request. Refuse to run in the production Rails env
+    # unless an operator explicitly overrides. Fail closed.
+    def refuse_in_production!
+      return unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+      return if ENV["ALLOW_PRODUCTION_SEED"] == "true"
+
+      raise Synthra::Errors::SecurityError,
+            "DatabaseSeeder will not run in production: it truncates tables and disables " \
+            "ActiveRecord callbacks process-wide. Set ALLOW_PRODUCTION_SEED=true to override."
+    end
+
+    def setup_environment
+      truncate_tables if @options[:truncate] && defined?(ActiveRecord)
+      # disable_callbacks is now honoured per-model via insert_all in #create (skips callbacks at the
+      # DB layer). We no longer call ActiveRecord::Base.skip_callback: mutating the global callback
+      # chain suppresses callbacks (tenant scoping, audit, webhooks) for every concurrent request.
+    end
+
+    def truncate_tables
+      return unless defined?(ActiveRecord)
+
+      refuse_in_production! # defense in depth — never TRUNCATE prod tables
+
+      # Disable foreign key checks temporarily
+      connection = ActiveRecord::Base.connection
+      
+      case connection.adapter_name
+      when "PostgreSQL"
+        connection.execute("SET CONSTRAINTS ALL DEFERRED")
+      when "MySQL", "Mysql2"
+        connection.execute("SET FOREIGN_KEY_CHECKS = 0")
+      end
+
+      @created_records.keys.each do |table|
+        connection.truncate(table.tableize) rescue nil
+      end
+
+      case connection.adapter_name
+      when "PostgreSQL"
+        connection.execute("SET CONSTRAINTS ALL IMMEDIATE")
+      when "MySQL", "Mysql2"
+        connection.execute("SET FOREIGN_KEY_CHECKS = 1")
+      end
+    end
+
+    def find_or_infer_schema(name, model)
+      if @registry.schema?(name)
+        @registry.schema(name)
+      elsif model.respond_to?(:columns)
+        dsl = SchemaInference.from_active_record(model)
+        Synthra.parse(dsl)
+      else
+        raise ArgumentError, "No schema found for #{name} and model doesn't support inference"
+      end
+    end
+
+    def generate_with_fk_resolution(schema, model, mode, overrides)
+      # Detect foreign keys
+      fk_overrides = resolve_foreign_keys(model)
+      
+      # Generate data
+      data = schema.generate(mode: mode, overrides: overrides.merge(fk_overrides))
+      
+      # Filter to only include valid columns
+      filter_columns(model, data)
+    end
+
+    def resolve_foreign_keys(model)
+      return {} unless model.respond_to?(:reflect_on_all_associations)
+      
+      fk_overrides = {}
+      
+      model.reflect_on_all_associations(:belongs_to).each do |assoc|
+        fk_column = assoc.foreign_key
+        related_model = assoc.klass rescue next
+        
+        # Get a random ID from created records
+        if (id = random_id(related_model))
+          fk_overrides[fk_column] = id
+        end
+      end
+      
+      fk_overrides
+    end
+
+    def filter_columns(model, data)
+      return data unless model.respond_to?(:column_names)
+      
+      data.select { |k, _| model.column_names.include?(k.to_s) }
+    end
+
+    def insert_in_batches(model, records)
+      batch_size = @options[:batch_size]
+      
+      records.each_slice(batch_size) do |batch|
+        model.insert_all(batch)
+      end
+      
+      # Store records for FK resolution (simplified - just IDs)
+      schema_name = model.name
+      records.each do |data|
+        @created_records[schema_name] << OpenStruct.new(data)
+      end
+    end
+
+    def summary
+      total = @created_records.values.flatten.count
+      
+      puts "\n" + "=" * 50
+      puts "Seeding Complete!"
+      puts "=" * 50
+      
+      @created_records.each do |model, records|
+        puts "  #{model}: #{records.count} records"
+      end
+      
+      puts "-" * 50
+      puts "  Total: #{total} records"
+      
+      @created_records
+    end
+  end
+
+  class << self
+    # Convenience method for database seeding
+    #
+    # @param options [Hash] seeder options
+    # @yield seeding DSL
+    # @return [Hash] created records by model
+    #
+    def seed_database(**options, &block)
+      seeder = DatabaseSeeder.new(**options)
+      seeder.seed(&block)
+    end
+  end
+end