active_version 1.0.0

data/lib/active_version/translations/translation_record.rb

@@ -0,0 +1,258 @@
+module ActiveVersion
+  module Translations
+    # Marker module for translation models
+    # Identifies a model as a translation record
+    module TranslationRecord
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :active_version_translation_schema, instance_writer: false, default: {}
+
+        # Mark this as a translation record
+        def self.translation_record?
+          true
+        end
+
+        # Get source model name (e.g., "Post" from "PostTranslation")
+        def self.source_name
+          return @source_name if @source_name
+          return nil unless name
+          @source_name = name.underscore.gsub("_translation", "").to_sym
+        end
+
+        # Get source model class (lazy)
+        def self.source_class
+          @source_class ||= begin
+            klass = source_name.to_s.classify.safe_constantize
+            klass || raise(NameError, "Could not find source class #{source_name.to_s.classify}")
+          end
+        end
+
+        # Get foreign key name(s) (e.g., "post_id" or ["tenant_id", "post_id"])
+        def self.source_foreign_key
+          schema_foreign_key = (active_version_translation_schema || {})[:foreign_key]
+          if schema_foreign_key.present?
+            return schema_foreign_key.is_a?(Array) ? schema_foreign_key.map(&:to_s) : schema_foreign_key.to_s
+          end
+
+          model_name = source_name.to_s.classify
+          options = ActiveVersion.registry.config_for_model_name(model_name, :translations) || {}
+          options = ActiveVersion.registry.config_for(source_class, :translations) || {} if options.empty?
+          foreign_key = options[:foreign_key].presence || "#{source_name}_id"
+          foreign_key.is_a?(Array) ? foreign_key.map(&:to_s) : foreign_key.to_s
+        rescue NameError
+          "#{source_name}_id"
+        end
+
+        def self.source_primary_key
+          schema_identity_resolver = (active_version_translation_schema || {})[:identity_resolver]
+          if schema_identity_resolver.present?
+            return schema_identity_resolver.map(&:to_s) if schema_identity_resolver.is_a?(Array)
+            return schema_identity_resolver.to_s if schema_identity_resolver.is_a?(Symbol)
+            return schema_identity_resolver if schema_identity_resolver.is_a?(String) && schema_identity_resolver.present?
+          end
+
+          model_name = source_name.to_s.classify
+          options = ActiveVersion.registry.config_for_model_name(model_name, :translations) || {}
+          options = ActiveVersion.registry.config_for(source_class, :translations) || {} if options.empty?
+
+          resolver = options[:identity_resolver]
+          return resolver.map(&:to_s) if resolver.is_a?(Array)
+          return resolver.to_s if resolver.is_a?(Symbol)
+          return resolver if resolver.is_a?(String) && resolver.present?
+
+          nil
+        rescue NameError
+          nil
+        end
+
+        def self.locale_column_name
+          schema_locale = (active_version_translation_schema || {})[:locale_column]
+          if schema_locale.present?
+            return schema_locale.to_sym
+          end
+
+          locale_column = ActiveVersion.column_mapper.column_for(source_class, :translations, :locale)
+          return locale_column if column_names.include?(locale_column.to_s)
+
+          ActiveVersion.config.translation_locale_column
+        rescue NameError, ActiveRecord::ConnectionNotDefined
+          ActiveVersion.config.translation_locale_column
+        end
+
+        # Set up belongs_to association (deferred until source class exists)
+        def self.setup_associations(force: false)
+          reflection = reflect_on_association(source_name)
+          return if @associations_setup && !force && Array(reflection&.foreign_key).map(&:to_s) == Array(source_foreign_key).map(&:to_s)
+          @associations_setup = true
+
+          assoc_options = {
+            foreign_key: source_foreign_key,
+            inverse_of: :translations,
+            touch: true
+          }
+          primary_key = source_primary_key
+          assoc_options[:primary_key] = primary_key if primary_key.present?
+          send(:belongs_to, source_name, **assoc_options)
+
+          # Validations
+          begin
+            locale_column = locale_column_name
+            validates locale_column, presence: true, uniqueness: {scope: Array(source_foreign_key)}
+          rescue NameError, ActiveRecord::ConnectionNotDefined
+            # Source class not yet defined, will be set up later
+          end
+        end
+
+        # Setup will be called when source class is available
+        def self.setup_locale_enum
+          return if @locale_enum_setup
+          return unless defined?(I18n) && I18n.respond_to?(:available_locales)
+          return unless source_name
+
+          @locale_enum_setup = true
+          begin
+            locale_column = locale_column_name
+            column = columns_hash[locale_column.to_s]
+            return unless column&.type == :integer
+            enum locale_column, I18n.available_locales.index_by(&:to_s)
+          rescue NameError, ActiveRecord::ConnectionNotDefined
+            # Source class not yet defined
+          end
+        end
+
+        # Scopes
+        scope :for_locale, ->(locale) {
+          return none unless source_name
+          locale_column = locale_column_name
+          where(locale_column => locale)
+        }
+
+        # After create hook to update source version
+        after_create :update_source_version
+        after_create :instrument_translation_created
+
+        # After update hook to instrument translation updated
+        after_update :instrument_translation_updated
+        after_destroy :instrument_translation_destroyed
+
+        # Setup associations when class is loaded (only if name is available)
+        setup_associations if name
+        setup_locale_enum if name
+      end
+
+      class TranslationSchemaDSL
+        def initialize(klass)
+          @klass = klass
+        end
+
+        def locale_column(value)
+          @klass.translation_locale_column(value)
+        end
+
+        def foreign_key(value)
+          @klass.translation_foreign_key(value)
+        end
+
+        def identity_resolver(value)
+          @klass.translation_identity_resolver(value)
+        end
+      end
+
+      class_methods do
+        def configure_translation(**options, &block)
+          apply_translation_configuration(**options)
+          TranslationSchemaDSL.new(self).instance_eval(&block) if block_given?
+          active_version_translation_schema
+        end
+
+        def translation_locale_column(value = nil) = schema_option(:locale_column, value, cast: :symbol)
+        def translation_foreign_key(value = nil) = schema_option(:foreign_key, value, cast: :identity)
+        def translation_identity_resolver(value = nil) = schema_option(:identity_resolver, value, cast: :resolver)
+
+        def apply_translation_configuration(locale_column: nil, foreign_key: nil, identity_resolver: nil)
+          translation_locale_column(locale_column) if locale_column
+          translation_foreign_key(foreign_key) if foreign_key
+          translation_identity_resolver(identity_resolver) if identity_resolver
+          active_version_translation_schema
+        end
+
+        private
+
+        def schema_option(key, value, cast:)
+          schema = (active_version_translation_schema || {}).dup
+          return schema[key] if value.nil?
+
+          schema[key] = case cast
+          when :symbol
+            value.to_sym
+          when :identity
+            value.is_a?(Array) ? value.map(&:to_s) : value.to_s
+          when :resolver
+            if value.is_a?(Array)
+              value.map(&:to_s)
+            elsif value.is_a?(Symbol)
+              value.to_s
+            else
+              value
+            end
+          else
+            value
+          end
+          self.active_version_translation_schema = schema
+          schema[key]
+        end
+      end
+
+      # Check if attribute is present for locale
+      def attr_present_for_locale?(locale, attr_name, presence_check = nil)
+        return false unless self.class.source_name
+
+        begin
+          locale_column = self.class.locale_column_name
+          return false unless send(locale_column).to_s == locale.to_s
+
+          if presence_check
+            send(presence_check, attr_name)
+          else
+            send(attr_name).present?
+          end
+        rescue NameError
+          # Source class not yet defined, check locale directly
+          return false unless respond_to?(:locale)
+          return false unless self.locale.to_s == locale.to_s
+          send(attr_name).present?
+        end
+      end
+
+      # Get source version (for versioning of versions)
+      def source_version
+        send(self.class.source_name)
+      end
+
+      private
+
+      def update_source_version
+        source = send(self.class.source_name)
+        return unless source
+
+        # Update source's updated_at if it has translations
+        if source.respond_to?(:update_default_translation)
+          source.update_default_translation
+        end
+      end
+
+      def instrument_translation_created
+        ActiveVersion::Instrumentation.instrument_translation_created(self, source_version)
+      end
+
+      def instrument_translation_updated
+        ActiveVersion::Instrumentation.instrument_translation_updated(self, source_version)
+      end
+
+      def instrument_translation_destroyed
+        ActiveVersion::Instrumentation.instrument_translation_destroyed(self, source_version)
+      end
+    end
+  end
+end

data/lib/active_version/translations.rb

@@ -0,0 +1,9 @@
+require "active_version/translations/translation_record"
+require "active_version/translations/has_translations"
+
+module ActiveVersion
+  module Translations
+    # Translations module for ActiveVersion
+    # Provides locale-based versioning functionality
+  end
+end

data/lib/active_version/version.rb

@@ -0,0 +1,3 @@
+module ActiveVersion
+  VERSION = "1.0.0"
+end

data/lib/active_version/version_registry.rb

@@ -0,0 +1,87 @@
+module ActiveVersion
+  # Registry for tracking versioned models and their configuration
+  class VersionRegistry
+    def initialize
+      @models = {}
+      @version_classes = {}
+    end
+
+    # Register a model with versioning
+    # Detects conflicts when re-registering with different options or duplicate registrations
+    def register(model_class, version_type, options = {})
+      key = registry_key(model_class, version_type)
+
+      # Check for existing registration
+      if @models.key?(key)
+        existing = @models[key]
+
+        # Detect option conflicts
+        if existing[:options] != options
+          warn "[ActiveVersion] Re-registering #{model_class.name} with :#{version_type} " \
+               "with different options. Previous: #{existing[:options].inspect}, " \
+               "New: #{options.inspect}. This may indicate a configuration issue."
+        else
+          # Same options - likely a double include, but not necessarily a problem
+          # Log at debug level if needed
+        end
+      end
+
+      @models[key] = {
+        model_class: model_class,
+        version_type: version_type,
+        options: options,
+        registered_at: Time.current
+      }
+    end
+
+    # Get version class for a model and version type
+    def version_class_for(model_class, version_type)
+      key = registry_key(model_class, version_type)
+      @version_classes[key]
+    end
+
+    # Register a version class
+    def register_version_class(model_class, version_type, version_class)
+      key = registry_key(model_class, version_type)
+      @version_classes[key] = version_class
+    end
+
+    # Check if a model is registered for versioning
+    def registered?(model_class, version_type)
+      key = registry_key(model_class, version_type)
+      @models.key?(key)
+    end
+
+    # Get all registered models for a version type
+    def models_for_version_type(version_type)
+      @models.select { |_k, v| v[:version_type] == version_type }
+        .map { |_k, v| v[:model_class] }
+    end
+
+    # Get configuration for a model and version type
+    def config_for(model_class, version_type)
+      key = registry_key(model_class, version_type)
+      @models[key]&.fetch(:options, {})
+    end
+
+    # Get configuration by model class name and version type.
+    # Useful while constants are still being wired and only the intended class
+    # name is known.
+    def config_for_model_name(model_name, version_type)
+      key = :"#{model_name}:#{version_type}"
+      @models[key]&.fetch(:options, {})
+    end
+
+    # Clear all registrations (useful for testing)
+    def clear!
+      @models.clear
+      @version_classes.clear
+    end
+
+    private
+
+    def registry_key(model_class, version_type)
+      :"#{model_class.name}:#{version_type}"
+    end
+  end
+end

data/lib/active_version.rb

@@ -0,0 +1,329 @@
+require "active_support"
+begin
+  require "active_record"
+rescue LoadError
+  # ActiveRecord is optional at runtime.
+end
+
+require "active_version/version"
+require "active_version/configuration"
+require "active_version/column_mapper"
+require "active_version/version_registry"
+require "active_version/instrumentation"
+require "active_version/runtime"
+
+# Main entry point for ActiveVersion
+module ActiveVersion
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class VersionNotFoundError < Error; end
+  class ReadonlyVersionError < Error; end
+  class FutureTimeError < Error; end
+  class DeletedColumnError < Error; end
+
+  extend ActiveSupport::Autoload
+
+  autoload :Adapters
+  autoload :Translations
+  autoload :Revisions
+  autoload :Audits
+  autoload :Database
+  autoload :Sharding
+  autoload :Query
+  autoload :Migrators
+  autoload :Runtime
+
+  # Load translations module
+  require "active_version/translations"
+  # Load revisions module
+  require "active_version/revisions"
+  # Load audits module
+  require "active_version/audits"
+
+  # Load ActiveRecord adapters (they use ActiveSupport.on_load, so safe to require)
+  begin
+    # Ensure base adapter is loaded first
+    require "active_version/adapters/active_record/base"
+    require "active_version/adapters/active_record/translations"
+    require "active_version/adapters/active_record/revisions"
+    require "active_version/adapters/active_record/audits"
+  rescue LoadError
+    # Adapters may not be available in all environments
+  end
+
+  begin
+    require "active_version/adapters/sequel"
+  rescue LoadError
+    # Sequel adapter is optional at runtime.
+  end
+
+  # Global configuration
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  def self.configure
+    yield config if block_given?
+    config
+  end
+
+  # Convenience methods for accessing configuration
+  def self.auditing_enabled
+    config.auditing_enabled
+  end
+
+  def self.auditing_enabled=(value)
+    config.auditing_enabled = value
+  end
+
+  # Runtime adapter access (ActiveRecord by default).
+  def self.runtime_adapter
+    Runtime.adapter
+  end
+
+  def self.runtime_adapter=(adapter)
+    Runtime.adapter = adapter
+  end
+
+  def self.reset_runtime_adapter!
+    Runtime.reset_adapter!
+  end
+
+  # Context management (like audited)
+  class RequestStore < ActiveSupport::CurrentAttributes
+    attribute :version_context
+    attribute :audited_user
+    attribute :request_uuid
+    attribute :remote_address
+  end
+
+  def self.context
+    # Merge persistent context with request-scoped context
+    persistent = store_get(:active_version_persistent_context) || {}
+    request_scoped = RequestStore.version_context || {}
+    persistent.merge(request_scoped)
+  end
+
+  def self.context=(value)
+    raise ConfigurationError, "context must be a hash" unless value.is_a?(Hash)
+    RequestStore.version_context = value
+  end
+
+  # Transaction-aware context (uses PostgreSQL session variables)
+  # Accepts either a hash as first argument or keyword arguments
+  def self.with_context(context = nil, transactional: true, **kwargs, &block)
+    raise ArgumentError, "with_context requires a block" unless block_given?
+
+    # If context is nil but kwargs are provided, use kwargs as context
+    # If context is provided, use it (and ignore kwargs)
+    # If both are nil/empty, use empty hash
+    context_hash = if context.nil? && kwargs.any?
+      kwargs
+    elsif context.is_a?(Hash)
+      context
+    elsif context.nil?
+      {}
+    else
+      raise ArgumentError, "context must be a hash or keyword arguments"
+    end
+
+    if transactional_context_supported?
+      # Use PostgreSQL session variables for transaction-aware context
+      with_transactional_context(context_hash, &block)
+    else
+      # Fallback to thread-local context
+      with_thread_local_context(context_hash, &block)
+    end
+  end
+
+  # Persistent context (connection-level, persists across operations)
+  def self.with_context!(context)
+    raise ArgumentError, "context must be a hash" unless context.is_a?(Hash)
+
+    if store_get(:active_version_in_block)
+      raise Error, "with_context! cannot be called from within a with_context block"
+    end
+
+    store_set(:active_version_persistent_context, context)
+    nil
+  end
+
+  # Clear persistent context
+  def self.clear_context!
+    store_delete(:active_version_persistent_context)
+    store_set(:active_version_context_depth, 0)
+    store_set(:active_version_in_block, false)
+    nil
+  end
+
+  def self.store_get(key)
+    if config.execution_scope == :thread
+      Thread.current.thread_variable_get(key)
+    elsif Fiber.current.respond_to?(:[])
+      Fiber.current[key]
+    else
+      Thread.current[key]
+    end
+  end
+
+  def self.store_set(key, value)
+    if config.execution_scope == :thread
+      Thread.current.thread_variable_set(key, value)
+    elsif Fiber.current.respond_to?(:[]=)
+      Fiber.current[key] = value
+    else
+      Thread.current[key] = value
+    end
+  end
+
+  def self.store_delete(key)
+    store_set(key, nil)
+  end
+
+  def self.store_keys
+    if config.execution_scope == :thread
+      Thread.current.thread_variables
+    elsif Thread.current.respond_to?(:keys)
+      Thread.current.keys
+    else
+      []
+    end
+  end
+
+  def self.clear_scoped_keys!(pattern)
+    store_keys.grep(pattern).each { |key| store_delete(key) }
+  end
+  public_class_method :store_get, :store_set, :store_delete, :clear_scoped_keys!
+
+  def self.enter_context_block!
+    depth = store_get(:active_version_context_depth).to_i + 1
+    store_set(:active_version_context_depth, depth)
+    store_set(:active_version_in_block, depth.positive?)
+  end
+
+  def self.leave_context_block!
+    depth = store_get(:active_version_context_depth).to_i - 1
+    depth = 0 if depth.negative?
+    store_set(:active_version_context_depth, depth)
+    store_set(:active_version_in_block, depth.positive?)
+  end
+
+  def self.with_transactional_context(context, &block)
+    connection = Runtime.adapter.base_connection
+    old_context = self.context.dup
+    old_block_context = store_get(:active_version_block_context)
+    enter_context_block!
+
+    # Set PostgreSQL session variable
+    if connection.open_transactions.positive?
+      encoded_context = connection.quote(ActiveSupport::JSON.encode(context))
+      connection.execute("SET LOCAL active_version.context = #{encoded_context}")
+    end
+
+    # Also update thread-local for immediate access
+    self.context = old_context.merge(context)
+    store_set(:active_version_block_context, context)
+
+    yield
+  ensure
+    # Context is automatically cleared on transaction rollback
+    # But we still restore thread-local context
+    self.context = old_context
+    store_set(:active_version_block_context, old_block_context)
+    leave_context_block!
+  end
+
+  def self.transactional_context_supported?
+    connection = Runtime.adapter.base_connection
+    Runtime.supports_transactional_context?(connection)
+  rescue *Runtime.active_record_connection_errors
+    false
+  rescue
+    false
+  end
+
+  def self.time_parser
+    zone = Time.zone if Time.respond_to?(:zone)
+    zone || Time
+  end
+
+  def self.with_thread_local_context(context, &block)
+    old_context = self.context.dup
+    old_block_context = store_get(:active_version_block_context)
+    enter_context_block!
+    self.context = old_context.merge(context)
+    store_set(:active_version_block_context, context)
+    yield
+  ensure
+    self.context = old_context
+    store_set(:active_version_block_context, old_block_context)
+    leave_context_block!
+  end
+
+  # Disable versioning globally
+  def self.without_auditing
+    auditing_was_enabled = auditing_enabled
+    disable_auditing
+    yield
+  ensure
+    enable_auditing if auditing_was_enabled
+  end
+
+  def self.disable_auditing
+    self.auditing_enabled = false
+  end
+
+  def self.enable_auditing
+    self.auditing_enabled = true
+  end
+
+  # Version registry access
+  def self.registry
+    @registry ||= VersionRegistry.new
+  end
+
+  # Column mapper access
+  def self.column_mapper
+    @column_mapper ||= ColumnMapper.new
+  end
+
+  # Parse time from various formats
+  # Converts Numeric (Unix timestamp), String, Date, Time, or other objects to Time
+  # @param time [Numeric, String, Date, Time, Object] Time value in various formats
+  # @return [Time] Time object
+  def self.parse_time(time)
+    parser = time_parser
+    case time
+    when Numeric then parser.at(time)
+    when String then parser.parse(time)
+    when Date then time.to_time
+    when Time then time
+    else parser.parse(time.to_s)
+    end
+  end
+
+  # Parse time and return Time object (alias for clarity)
+  def self.parse_time_to_time(time)
+    parse_time(time)
+  end
+
+  # Connection access is intentionally application-owned.
+  # ActiveVersion does not route between shards/connections.
+  # These methods remain as pass-through helpers.
+  def self.connection_for(model_class, version_type)
+    :default
+  end
+
+  def self.adapter_for(model_class, version_type)
+    Runtime.adapter.connection_for(model_class, version_type)
+  end
+
+  def self.with_connection(model_class, version_type, &block)
+    yield(Runtime.adapter.connection_for(model_class, version_type))
+  end
+end
+
+# Load Rails integration if available
+if defined?(Rails)
+  require "active_version/railtie"
+end