active_version 1.0.0

data/lib/active_version/audits/sql_builder.rb

@@ -0,0 +1,263 @@
+module ActiveVersion
+  module Audits
+    # SQL builder for batch audit operations
+    module SQLBuilder
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        BatchCollector = Struct.new(:records) do
+          def <<(record)
+            records << record
+            self
+          end
+
+          def add(record)
+            self << record
+          end
+
+          def concat(list)
+            records.concat(Array(list))
+            self
+          end
+
+          def to_a
+            records
+          end
+        end
+
+        # Generate SQL for batch insert of audits
+        # @param records [Array] Array of ActiveRecord instances to audit
+        # @param options [Hash] Options for batch generation
+        # @option options [Boolean] :combine (true) Combine into single INSERT statement
+        # @option options [Hash] :context Additional context to merge with each audit
+        # @return [String] SQL statement(s) for batch insert
+        def batch_insert_sql(records = nil, options = {}, &block)
+          records, options = normalize_batch_arguments(records, options)
+          captured_values = []
+
+          if block_given? && block.arity == 0 && Array(records).flatten.compact.empty?
+            captured_values = capture_audit_values(options) { yield }
+          end
+
+          if captured_values.any?
+            if options[:combine] != false
+              return build_combined_insert_sql(self, captured_values)
+            end
+
+            return captured_values.map { |values| build_single_insert_sql(self, values) }.join(";\n")
+          end
+
+          records = resolve_batch_records(records, &block)
+          return "" if records.empty?
+
+          # Get audit class from first record
+          first_record = records.first
+          return "" unless first_record
+
+          audit_class = first_record.class.audit_class
+          return "" unless audit_class
+
+          version_tracker = {}
+
+          # Build values for each record
+          values_list = records.map do |record|
+            build_batch_audit_values(record, audit_class, options, version_tracker)
+          end.compact
+
+          return "" if values_list.empty?
+
+          # Combine into single INSERT with multiple VALUES
+          if options[:combine] != false
+            build_combined_insert_sql(audit_class, values_list)
+          else
+            # Return separate INSERT statements
+            values_list.map do |values|
+              build_single_insert_sql(audit_class, values)
+            end.join(";\n")
+          end
+        end
+
+        # Execute batch insert SQL for audits.
+        # Supports the same arguments and block semantics as batch_insert_sql.
+        # @return [Integer] 0 when nothing to insert, otherwise adapter execute result
+        def batch_insert(records = nil, options = {}, &block)
+          sql = batch_insert_sql(records, options, &block)
+          return 0 if sql.empty?
+
+          connection.execute(sql)
+        end
+
+        private
+
+        def normalize_batch_arguments(records, options)
+          if records.is_a?(Hash) && options.empty?
+            [nil, records]
+          else
+            [records, options]
+          end
+        end
+
+        def resolve_batch_records(records, &block)
+          return Array(records).flatten.compact unless block_given?
+
+          collected = []
+          if block.arity == 1
+            yield(BatchCollector.new(collected))
+          else
+            yield
+          end
+
+          Array(collected).flatten.compact
+        end
+
+        def capture_audit_values(options = {})
+          previous_state = ActiveVersion.store_get(:active_version_audit_batch_state)
+          state = {
+            target_audit_class: self,
+            options: options,
+            values: [],
+            version_tracker: {}
+          }
+          ActiveVersion.store_set(:active_version_audit_batch_state, state)
+          yield
+          state[:values]
+        ensure
+          ActiveVersion.store_set(:active_version_audit_batch_state, previous_state)
+        end
+
+        def build_batch_audit_values(record, audit_class, options, version_tracker)
+          # Allow building values even if record hasn't changed (for testing/documentation)
+          return nil unless record.changed? || options[:force] || options[:allow_saved]
+
+          # Determine action
+          action = if record.new_record?
+            "create"
+          elsif options[:destroy]
+            "destroy"
+          else
+            "update"
+          end
+
+          # Get audited changes
+          changes = record.send(:audited_changes) if record.respond_to?(:audited_changes, true)
+          changes ||= record.changes
+
+          # Build base attributes
+          attrs = {
+            action: action,
+            audited_changes: changes
+          }
+          attrs[:comment] = record.audit_comment if record.respond_to?(:audit_comment)
+
+          # Merge context
+          global_context = ActiveVersion.context || {}
+          instance_context = record.audit_context if record.respond_to?(:audit_context)
+          context = global_context.merge(instance_context || {})
+          context.merge!(options[:context] || {})
+          attrs[:audited_context] = context if context.any?
+
+          # Set polymorphic association
+          auditable_column = ActiveVersion.column_mapper.column_for(record.class, :audits, :auditable)
+          identity_map = if record.respond_to?(:active_version_audit_identity_map)
+            record.active_version_audit_identity_map
+          elsif record.respond_to?(:active_version_auditable_id_value)
+            {"#{auditable_column}_id" => record.active_version_auditable_id_value}
+          else
+            {"#{auditable_column}_id" => record.id}
+          end
+          return nil if identity_map.values.any?(&:nil?)
+          attrs.merge!(identity_map)
+          attrs["#{auditable_column}_type"] = record.class.name
+
+          # Set version
+          version_column = ActiveVersion.column_mapper.column_for(record.class, :audits, :version)
+          attrs[version_column] = next_batch_version(
+            audit_class,
+            version_column,
+            "#{auditable_column}_type",
+            identity_map,
+            attrs["#{auditable_column}_type"],
+            version_tracker
+          )
+
+          # Set user if available
+          user_column = ActiveVersion.column_mapper.column_for(record.class, :audits, :user)
+          if user_column && defined?(ActiveVersion::RequestStore) && ActiveVersion::RequestStore.audited_user
+            user = ActiveVersion::RequestStore.audited_user
+            if user.respond_to?(:id)
+              attrs[user_column] = user.id
+              if user_column.to_s.end_with?("_id") && user.respond_to?(:class)
+                type_column = user_column.to_s.gsub("_id", "_type")
+                attrs[type_column] = user.class.name
+              end
+            end
+            # If user doesn't have id method, skip setting user column
+          end
+
+          # Set timestamps
+          attrs[:created_at] = Time.current
+          attrs[:updated_at] = Time.current
+
+          attrs
+        end
+
+        def next_batch_version(audit_class, version_column, type_column, identity_map, auditable_type, version_tracker)
+          normalized_identity_map = identity_map.transform_keys(&:to_s).sort.to_h
+          cache_key = [auditable_type, normalized_identity_map]
+          previous_version = version_tracker[cache_key]
+          if previous_version
+            version_tracker[cache_key] = previous_version + 1
+            return version_tracker[cache_key]
+          end
+
+          max_version = audit_class
+            .where(normalized_identity_map.merge(type_column => auditable_type))
+            .maximum(version_column)
+            .to_i
+
+          version_tracker[cache_key] = max_version + 1
+        end
+
+        def build_combined_insert_sql(audit_class, values_list)
+          return "" if values_list.empty?
+
+          # Get all columns from all values
+          all_columns = values_list.flat_map(&:keys).uniq
+          connection = audit_class.connection
+          table_name = connection.quote_table_name(audit_class.table_name)
+          column_list = all_columns.map { |col| connection.quote_column_name(col) }.join(", ")
+
+          values_sql = values_list.map do |values|
+            row_values = all_columns.map { |col| connection.quote(prepare_sql_value(values[col])) }.join(", ")
+            "(#{row_values})"
+          end.join(", ")
+
+          "INSERT INTO #{table_name} (#{column_list}) VALUES #{values_sql}"
+        end
+
+        def build_single_insert_sql(audit_class, values)
+          stmt = Arel::InsertManager.new
+          table = Arel::Table.new(audit_class.table_name)
+          stmt.into(table)
+
+          values.keys.each { |key| stmt.columns << table[key] }
+          stmt.values = stmt.create_values(values.values.map { |v| prepare_sql_value(v) })
+          stmt.to_sql
+        end
+
+        def prepare_sql_value(value)
+          case value
+          when Hash, Array
+            value.to_json
+          when Time, DateTime
+            value.utc
+          when Date
+            value.to_time.utc
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_version/audits.rb

@@ -0,0 +1,10 @@
+require "active_version/audits/audit_record"
+require "active_version/audits/has_audits"
+require "active_version/audits/sql_builder"
+
+module ActiveVersion
+  module Audits
+    # Audits module for ActiveVersion
+    # Provides change tracking and evidence functionality
+  end
+end

data/lib/active_version/column_mapper.rb

@@ -0,0 +1,92 @@
+module ActiveVersion
+  # Maps versioning concepts to actual column names
+  # Allows developers to configure any column name to any concept
+  class ColumnMapper
+    def initialize
+      @mappings = {}
+    end
+
+    # Register a column mapping for a model and version type
+    def register(model_class, version_type, concept, column_name)
+      key = mapping_key(model_class, version_type, concept)
+      @mappings[key] = column_name.to_sym
+    end
+
+    # Get column name for a concept
+    def column_for(model_class, version_type, concept)
+      key = mapping_key(model_class, version_type, concept)
+      @mappings[key] || default_column_for(version_type, concept)
+    end
+
+    # Get all mappings for a model and version type
+    def mappings_for(model_class, version_type)
+      prefix = "#{model_class.name}:#{version_type}:"
+      @mappings.select { |k, _v| k.to_s.start_with?(prefix) }
+        .transform_keys { |k| k.to_s.sub(prefix, "").to_sym }
+    end
+
+    private
+
+    def mapping_key(model_class, version_type, concept)
+      :"#{model_class.name}:#{version_type}:#{concept}"
+    end
+
+    def default_column_for(version_type, concept)
+      case version_type
+      when :translations
+        default_translation_column(concept)
+      when :revisions
+        default_revision_column(concept)
+      when :audits
+        default_audit_column(concept)
+      else
+        raise ConfigurationError, "Unknown version type: #{version_type.inspect}"
+      end
+    end
+
+    def default_translation_column(concept)
+      case concept
+      when :locale
+        ActiveVersion.config.translation_locale_column
+      else
+        raise ConfigurationError, "Unknown translation concept: #{concept.inspect}"
+      end
+    end
+
+    def default_revision_column(concept)
+      case concept
+      when :version
+        ActiveVersion.config.revision_version_column
+      else
+        raise ConfigurationError, "Unknown revision concept: #{concept.inspect}"
+      end
+    end
+
+    def default_audit_column(concept)
+      case concept
+      when :action
+        ActiveVersion.config.audit_action_column
+      when :changes
+        ActiveVersion.config.audit_changes_column
+      when :context
+        ActiveVersion.config.audit_context_column
+      when :comment
+        ActiveVersion.config.audit_comment_column
+      when :version
+        ActiveVersion.config.audit_version_column
+      when :user
+        ActiveVersion.config.audit_user_column
+      when :auditable
+        ActiveVersion.config.audit_auditable_column
+      when :associated
+        ActiveVersion.config.audit_associated_column
+      when :remote_address
+        ActiveVersion.config.audit_remote_address_column
+      when :request_uuid
+        ActiveVersion.config.audit_request_uuid_column
+      else
+        raise ConfigurationError, "Unknown audit concept: #{concept.inspect}"
+      end
+    end
+  end
+end

data/lib/active_version/configuration.rb

@@ -0,0 +1,124 @@
+module ActiveVersion
+  # Global configuration for ActiveVersion
+  class Configuration
+    attr_accessor :auditing_enabled
+    attr_accessor :current_user_method
+    attr_accessor :ignored_attributes
+    attr_accessor :ignored_default_callbacks
+    attr_accessor :store_synthesized_enums
+    attr_accessor :execution_scope
+
+    # Translation defaults
+    attr_accessor :translation_locale_column
+    attr_accessor :translation_default_locale
+
+    # Revision defaults
+    attr_accessor :revision_version_column
+    attr_accessor :revision_foreign_key_suffix
+
+    # Audit defaults
+    attr_accessor :default_audit_class
+    attr_accessor :audit_storage
+    attr_accessor :audit_action_column
+    attr_accessor :audit_changes_column
+    attr_accessor :audit_context_column
+    attr_accessor :audit_comment_column
+    attr_accessor :audit_version_column
+    attr_accessor :audit_user_column
+    attr_accessor :audit_auditable_column
+    attr_accessor :audit_associated_column
+    attr_accessor :audit_remote_address_column
+    attr_accessor :audit_request_uuid_column
+    attr_accessor :max_audits
+    attr_accessor :max_revisions
+    attr_accessor :return_self_if_no_revisions
+    attr_accessor :return_self_if_no_audits
+    attr_accessor :audit_error_behavior
+    attr_accessor :revision_error_behavior
+    attr_accessor :debounce_time
+
+    def initialize
+      # Global settings
+      @auditing_enabled = true
+      @current_user_method = :current_user
+      @ignored_attributes = %w[lock_version created_at updated_at created_on updated_on]
+      @ignored_default_callbacks = []
+      @store_synthesized_enums = false
+      @execution_scope = :fiber
+
+      # Translation defaults
+      @translation_locale_column = :locale
+      @translation_default_locale = :en
+
+      # Revision defaults
+      @revision_version_column = :version
+      @revision_foreign_key_suffix = "_id"
+
+      # Audit defaults
+      @default_audit_class = nil  # When set, has_audits without :as uses this when ModelAudit is not defined
+      @audit_storage = :json_column
+      @audit_action_column = :action
+      @audit_changes_column = :audited_changes
+      @audit_context_column = :audited_context
+      @audit_comment_column = :comment
+      @audit_version_column = :version
+      @audit_user_column = :user_id
+      @audit_auditable_column = :auditable
+      @audit_associated_column = :associated
+      @audit_remote_address_column = :remote_address
+      @audit_request_uuid_column = :request_uuid
+      @max_audits = nil
+      @max_revisions = nil
+      @return_self_if_no_revisions = false
+      @return_self_if_no_audits = false
+      @audit_error_behavior = :exception
+      @revision_error_behavior = :exception
+      @debounce_time = nil  # Time in seconds to merge revisions within window
+    end
+
+    # Validate configuration
+    def validate!
+      validate_storage_type!
+      validate_execution_scope!
+      validate_column_names!
+    end
+
+    private
+
+    def validate_storage_type!
+      unless %i[json_column yaml_column mirror_columns].include?(@audit_storage)
+        raise ConfigurationError,
+          "audit_storage must be :json_column, :yaml_column, or :mirror_columns, got: #{@audit_storage.inspect}"
+      end
+    end
+
+    def validate_execution_scope!
+      return if %i[fiber thread].include?(@execution_scope)
+
+      raise ConfigurationError,
+        "execution_scope must be :fiber or :thread, got: #{@execution_scope.inspect}"
+    end
+
+    def validate_column_names!
+      # Ensure column names are symbols or strings
+      column_attrs = [
+        :translation_locale_column,
+        :revision_version_column,
+        :audit_action_column,
+        :audit_changes_column,
+        :audit_context_column,
+        :audit_comment_column,
+        :audit_version_column,
+        :audit_user_column
+      ]
+
+      column_attrs.each do |attr|
+        value = instance_variable_get(:"@#{attr}")
+        unless value.is_a?(Symbol) || value.is_a?(String)
+          raise ConfigurationError,
+            "#{attr} must be a Symbol or String, got: #{value.class}"
+        end
+      end
+    end
+  end
+end