better_model 2.0.0 → 3.0.0

data/lib/better_model/traceable.rb

@@ -1,53 +1,57 @@
 # frozen_string_literal: true
 
-# Traceable - Change tracking con audit trail per modelli Rails
+require_relative "errors/traceable/traceable_error"
+require_relative "errors/traceable/not_enabled_error"
+require_relative "errors/traceable/configuration_error"
+
+# Traceable - Change tracking with audit trail for Rails models.
 #
-# Questo concern permette di tracciare automaticamente i cambiamenti ai record,
-# mantenendo uno storico completo con timestamp, autore e motivazione.
+# This concern enables automatic tracking of record changes,
+# maintaining a complete history with timestamps, author, and reasoning.
 #
-# SETUP RAPIDO:
-#   # Opzione 1: Generator automatico (raccomandato)
+# @example Quick Setup - Option 1: Automatic Generator (Recommended)
 #   rails g better_model:traceable Article --with-reason
 #   rails db:migrate
 #
-#   # Opzione 2: La migration better_model_versions è già nel gem
+# @example Quick Setup - Option 2: Using Included Migration
+#   # The better_model_versions migration is already in the gem
 #   rails db:migrate
 #
-# APPROCCIO OPT-IN: Il tracking non è attivo automaticamente. Devi chiamare
-# esplicitamente `traceable do...end` nel tuo modello per attivarlo.
+# @note OPT-IN APPROACH
+#   Tracking is not enabled automatically. You must explicitly call
+#   `traceable do...end` in your model to activate it.
 #
-# REQUISITI DATABASE:
-#   - better_model_versions table (inclusa nel gem)
+# @note DATABASE REQUIREMENTS
+#   - better_model_versions table (included in gem)
 #
-# Esempio di utilizzo:
+# @example Basic Model Setup
 #   class Article < ApplicationRecord
 #     include BetterModel
 #
-#     # Attiva traceable (opt-in)
+#     # Enable traceable (opt-in)
 #     traceable do
-#       track :status, :title, :published_at  # Campi da tracciare
+#       track :status, :title, :published_at  # Fields to track
 #     end
 #   end
 #
-# Utilizzo:
-#   # Tracking automatico
+# @example Automatic Tracking
 #   article.update!(status: "published", updated_by_id: user.id, updated_reason: "Approved")
 #
-#   # Query versioni
-#   article.versions                           # Tutte le versioni
-#   article.changes_for(:status)               # Cambiamenti per un campo
-#   article.audit_trail                        # Storico formattato
+# @example Querying Versions
+#   article.versions                           # All versions
+#   article.changes_for(:status)               # Changes for a field
+#   article.audit_trail                        # Formatted history
 #
-#   # Time-travel
-#   article.as_of(3.days.ago)                  # Stato a una data specifica
+# @example Time-Travel
+#   article.as_of(3.days.ago)                  # State at specific date
 #
-#   # Rollback
-#   article.rollback_to(version)               # Ripristina a versione precedente
+# @example Rollback
+#   article.rollback_to(version)               # Restore to previous version
 #
-#   # Scopes per query su cambiamenti
-#   Article.changed_by(user.id)                # Modifiche di un utente
-#   Article.changed_between(start, end)        # Modifiche in un periodo
-#   Article.status_changed_from("draft").to("published")  # Transizioni specifiche
+# @example Query Scopes for Changes
+#   Article.changed_by(user.id)                # Changes by user
+#   Article.changed_between(start, end)        # Changes in period
+#   Article.status_changed_from("draft").to("published")  # Specific transitions
 #
 module BetterModel
   module Traceable
@@ -59,7 +63,7 @@ module BetterModel
     included do
       # Validazione ActiveRecord
       unless ancestors.include?(ActiveRecord::Base)
-        raise ArgumentError, "BetterModel::Traceable can only be included in ActiveRecord models"
+        raise BetterModel::Errors::Traceable::ConfigurationError, "Invalid configuration"
       end
 
       # Configurazione traceable (opt-in)
@@ -122,16 +126,16 @@ module BetterModel
       # Verifica se traceable è attivo
       #
       # @return [Boolean]
-      def traceable_enabled?
-        traceable_enabled == true
-      end
+      def traceable_enabled? = traceable_enabled == true
 
       # Find records changed by a specific user
       #
       # @param user_id [Integer] User ID
       # @return [ActiveRecord::Relation]
       def changed_by(user_id)
-        raise NotEnabledError unless traceable_enabled?
+        unless traceable_enabled?
+          raise BetterModel::Errors::Traceable::NotEnabledError, "Module is not enabled"
+        end
 
         joins(:versions).where(traceable_table_name => { updated_by_id: user_id }).distinct
       end
@@ -142,7 +146,9 @@ module BetterModel
       # @param end_time [Time, Date] End time
       # @return [ActiveRecord::Relation]
       def changed_between(start_time, end_time)
-        raise NotEnabledError unless traceable_enabled?
+        unless traceable_enabled?
+          raise BetterModel::Errors::Traceable::NotEnabledError, "Module is not enabled"
+        end
 
         joins(:versions).where(traceable_table_name => { created_at: start_time..end_time }).distinct
       end
@@ -152,7 +158,9 @@ module BetterModel
       # @param field [Symbol] Field name
       # @return [ChangeQuery]
       def field_changed(field)
-        raise NotEnabledError unless traceable_enabled?
+        unless traceable_enabled?
+          raise BetterModel::Errors::Traceable::NotEnabledError, "Module is not enabled"
+        end
 
         ChangeQuery.new(self, field)
       end
@@ -202,7 +210,7 @@ module BetterModel
           end
 
           # Create new Version class dynamically
-          version_class = Class.new(BetterModel::Version) do
+          version_class = Class.new(BetterModel::Models::Version) do
             self.table_name = table_name
           end
 
@@ -220,7 +228,9 @@ module BetterModel
     # @param field [Symbol] Field name
     # @return [Array<Hash>] Array of changes with :before, :after, :at, :by
     def changes_for(field)
-      raise NotEnabledError unless self.class.traceable_enabled?
+      unless self.class.traceable_enabled?
+        raise BetterModel::Errors::Traceable::NotEnabledError, "Module is not enabled"
+      end
 
       versions.select { |v| v.changed?(field) }.map do |version|
         change = version.change_for(field)
@@ -238,7 +248,9 @@ module BetterModel
     #
     # @return [Array<Hash>] Full audit trail
     def audit_trail
-      raise NotEnabledError unless self.class.traceable_enabled?
+      unless self.class.traceable_enabled?
+        raise BetterModel::Errors::Traceable::NotEnabledError, "Module is not enabled"
+      end
 
       versions.map do |version|
         {
@@ -256,7 +268,9 @@ module BetterModel
     # @param timestamp [Time, Date] Point in time
     # @return [self] Reconstructed object (not saved)
     def as_of(timestamp)
-      raise NotEnabledError unless self.class.traceable_enabled?
+      unless self.class.traceable_enabled?
+        raise BetterModel::Errors::Traceable::NotEnabledError, "Module is not enabled"
+      end
 
       # Get all versions up to timestamp, ordered from oldest to newest
       relevant_versions = versions.where("created_at <= ?", timestamp).order(created_at: :asc)
@@ -280,12 +294,14 @@ module BetterModel
 
     # Rollback to a specific version
     #
-    # @param version [BetterModel::Version, Integer] Version or version ID
+    # @param version [BetterModel::Models::Version, Integer] Version or version ID
     # @param updated_by_id [Integer] User ID performing rollback
     # @param updated_reason [String] Reason for rollback
     # @return [self]
     def rollback_to(version, updated_by_id: nil, updated_reason: nil, allow_sensitive: false)
-      raise NotEnabledError unless self.class.traceable_enabled?
+      unless self.class.traceable_enabled?
+        raise BetterModel::Errors::Traceable::NotEnabledError, "Module is not enabled"
+      end
 
       version = versions.find(version) if version.is_a?(Integer)
 
@@ -478,14 +494,6 @@ module BetterModel
     end
   end
 
-  # Errori custom
-  class TraceableError < StandardError; end
-
-  class NotEnabledError < TraceableError
-    def initialize(msg = nil)
-      super(msg || "Traceable is not enabled. Add 'traceable do...end' to your model.")
-    end
-  end
 
   # Configurator per traceable DSL
   class TraceableConfigurator

data/lib/better_model/validatable/configurator.rb

@@ -2,221 +2,100 @@
 
 module BetterModel
   module Validatable
-    # Configurator per il DSL di Validatable
+    # Configurator for Validatable DSL.
     #
-    # Questo configurator permette di definire validazioni in modo dichiarativo
-    # all'interno del blocco `validatable do...end`.
+    # This configurator enables defining validations declaratively
+    # within the `validatable do...end` block.
     #
-    # Esempio:
+    # @example
     #   validatable do
-    #     # Validazioni base
-    #     validate :title, :content, presence: true
-    #     validate :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+    #     # Basic validations
+    #     check :title, :content, presence: true
+    #     check :email, format: { with: URI::MailTo::EMAIL_REGEXP }
     #
-    #     # Validazioni condizionali
-    #     validate_if :is_published? do
-    #       validate :published_at, presence: true
-    #       validate :author_id, presence: true
-    #     end
+    #     # Complex validations
+    #     check_complex :valid_pricing
+    #     check_complex :stock_check
     #
-    #     # Validazioni condizionali negate
-    #     validate_unless :is_draft? do
-    #       validate :reviewer_id, presence: true
-    #     end
-    #
-    #     # Cross-field validations
-    #     validate_order :starts_at, :before, :ends_at
-    #     validate_order :min_price, :lteq, :max_price
-    #
-    #     # Business rules
-    #     validate_business_rule :valid_category
-    #     validate_business_rule :author_has_permission, on: :create
-    #
-    #     # Gruppi di validazioni
+    #     # Validation groups
     #     validation_group :step1, [:email, :password]
     #     validation_group :step2, [:first_name, :last_name]
     #   end
     #
+    # @api private
     class Configurator
       attr_reader :groups
 
+      # Initialize a new Configurator.
+      #
+      # @param model_class [Class] Model class being configured
       def initialize(model_class)
         @model_class = model_class
-        @conditional_validations = []
-        @order_validations = []
-        @business_rules = []
+        @complex_validations = []
         @groups = {}
       end
 
-      # Definisce validazioni standard sui campi
-      #
-      # @param fields [Array<Symbol>] Nomi dei campi
-      # @param options [Hash] Opzioni di validazione (presence, format, etc.)
-      #
-      # @example
-      #   validate :title, :content, presence: true
-      #   validate :email, format: { with: URI::MailTo::EMAIL_REGEXP }
-      #   validate :age, numericality: { greater_than: 0 }
-      #
-      def validate(*fields, **options)
-        # Se siamo dentro un blocco condizionale, aggiungi alla condizione corrente
-        if @current_conditional
-          @current_conditional[:validations] << {
-            fields: fields,
-            options: options
-          }
-        else
-          # Altrimenti applica direttamente alla classe
-          # Questo viene fatto subito, non in apply_validatable_config
-          @model_class.validates(*fields, **options)
-        end
-      end
-
-      # Validazioni condizionali (se condizione è vera)
+      # Define standard validations on fields.
       #
-      # @param condition [Symbol, Proc] Condizione da verificare
-      # @yield Blocco con validazioni da applicare se condizione è vera
+      # Delegates to ActiveRecord's validates method.
       #
-      # @example Con simbolo (metodo)
-      #   validate_if :is_published? do
-      #     validate :published_at, presence: true
-      #   end
-      #
-      # @example Con lambda
-      #   validate_if -> { status == "published" } do
-      #     validate :published_at, presence: true
-      #   end
-      #
-      def validate_if(condition, &block)
-        raise ArgumentError, "validate_if requires a block" unless block_given?
-
-        conditional = {
-          condition: condition,
-          negate: false,
-          validations: []
-        }
-
-        # Set current conditional per catturare le validate dentro il blocco
-        @current_conditional = conditional
-        instance_eval(&block)
-        @current_conditional = nil
-
-        @conditional_validations << conditional
-      end
-
-      # Validazioni condizionali negate (se condizione è falsa)
-      #
-      # @param condition [Symbol, Proc] Condizione da verificare
-      # @yield Blocco con validazioni da applicare se condizione è falsa
+      # @param fields [Array<Symbol>] Field names
+      # @param options [Hash] Validation options (presence, format, etc.)
       #
       # @example
-      #   validate_unless :is_draft? do
-      #     validate :reviewer_id, presence: true
-      #   end
+      #   check :title, :content, presence: true
+      #   check :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+      #   check :age, numericality: { greater_than: 0 }
       #
-      def validate_unless(condition, &block)
-        raise ArgumentError, "validate_unless requires a block" unless block_given?
-
-        conditional = {
-          condition: condition,
-          negate: true,
-          validations: []
-        }
-
-        @current_conditional = conditional
-        instance_eval(&block)
-        @current_conditional = nil
-
-        @conditional_validations << conditional
+      def check(*fields, **options)
+        @model_class.validates(*fields, **options)
       end
 
-      # Validazione di ordine tra campi (cross-field)
-      #
-      # Verifica che un campo sia in una relazione d'ordine rispetto ad un altro.
-      #
-      # @param first_field [Symbol] Primo campo
-      # @param comparator [Symbol] Comparatore (:before, :after, :lteq, :gteq)
-      # @param second_field [Symbol] Secondo campo
-      # @param options [Hash] Opzioni aggiuntive (on, if, unless, message)
-      #
-      # @example Date validation
-      #   validate_order :starts_at, :before, :ends_at
-      #   validate_order :starts_at, :before, :ends_at, message: "must be before end date"
-      #
-      # @example Numeric validation
-      #   validate_order :min_price, :lteq, :max_price
-      #   validate_order :discount, :lteq, :price, on: :create
-      #
-      # Comparatori supportati:
-      # - :before - first < second (date/time)
-      # - :after - first > second (date/time)
-      # - :lteq - first <= second (numeric)
-      # - :gteq - first >= second (numeric)
-      # - :lt - first < second (numeric)
-      # - :gt - first > second (numeric)
-      #
-      def validate_order(first_field, comparator, second_field, **options)
-        valid_comparators = %i[before after lteq gteq lt gt]
-        unless valid_comparators.include?(comparator)
-          raise ArgumentError, "Invalid comparator: #{comparator}. Valid: #{valid_comparators.join(', ')}"
-        end
-
-        @order_validations << {
-          first_field: first_field,
-          comparator: comparator,
-          second_field: second_field,
-          options: options
-        }
-      end
-
-      # Definisce una business rule custom
+      # Use a registered complex validation.
       #
-      # Le business rules sono metodi custom che implementano logica di validazione
-      # complessa che non può essere espressa con validatori standard.
+      # Complex validations must be registered first using
+      # register_complex_validation in the model.
       #
-      # @param rule_name [Symbol] Nome del metodo che implementa la rule
-      # @param options [Hash] Opzioni (on, if, unless)
+      # @param name [Symbol] Name of registered complex validation
+      # @raise [ArgumentError] If validation is not registered
       #
       # @example
-      #   # Nel configurator:
-      #   validate_business_rule :valid_category
-      #   validate_business_rule :author_has_permission, on: :create
-      #
-      #   # Nel modello (implementazione):
-      #   def valid_category
-      #     unless Category.exists?(id: category_id)
-      #       errors.add(:category_id, "must be a valid category")
+      #   # In model (registration):
+      #   register_complex_validation :valid_pricing do
+      #     if sale_price.present? && sale_price >= price
+      #       errors.add(:sale_price, "must be less than regular price")
       #     end
       #   end
       #
-      #   def author_has_permission
-      #     unless author&.can_create_articles?
-      #       errors.add(:author_id, "does not have permission")
-      #     end
+      #   # In configurator (usage):
+      #   validatable do
+      #     check_complex :valid_pricing
       #   end
       #
-      def validate_business_rule(rule_name, **options)
-        @business_rules << {
-          name: rule_name,
-          options: options
-        }
+      def check_complex(name)
+        unless @model_class.complex_validation?(name)
+          raise ArgumentError, "Unknown complex validation: #{name}. Use register_complex_validation to define it first."
+        end
+
+        @complex_validations << name.to_sym
       end
 
-      # Definisce un gruppo di validazioni
+      # Define a validation group.
       #
-      # I gruppi permettono di validare solo un sottoinsieme di campi,
-      # utile per form multi-step o validazioni parziali.
+      # Groups allow validating only a subset of fields,
+      # useful for multi-step forms or partial validations.
       #
-      # @param group_name [Symbol] Nome del gruppo
-      # @param fields [Array<Symbol>] Campi inclusi nel gruppo
+      # @param group_name [Symbol] Group name
+      # @param fields [Array<Symbol>] Fields included in group
+      # @raise [ArgumentError] If group name is invalid, fields not array, or group already defined
       #
       # @example
       #   validation_group :step1, [:email, :password]
       #   validation_group :step2, [:first_name, :last_name]
       #   validation_group :step3, [:address, :city, :zip_code]
       #
-      #   # Utilizzo:
-      #   user.valid?(:step1)  # Valida solo email e password
+      # @example Usage
+      #   user.valid?(:step1)  # Validate only email and password
       #   user.errors_for_group(:step1)
       #
       def validation_group(group_name, fields)
@@ -230,14 +109,12 @@ module BetterModel
         }
       end
 
-      # Restituisce la configurazione completa
+      # Return complete configuration.
       #
-      # @return [Hash] Configurazione con tutte le validazioni
+      # @return [Hash] Configuration with all validations
       def to_h
         {
-          conditional_validations: @conditional_validations,
-          order_validations: @order_validations,
-          business_rules: @business_rules
+          complex_validations: @complex_validations
         }
       end
     end