better_model 2.1.0 → 3.0.0

data/lib/better_model/taggable.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
-# Taggable - Sistema di gestione tag dichiarativo per modelli Rails
+require_relative "errors/taggable/taggable_error"
+require_relative "errors/taggable/configuration_error"
+
+# Taggable - Declarative tag management system for Rails models.
 #
-# Questo concern permette di gestire tag multipli sui modelli utilizzando array PostgreSQL
-# con normalizzazione, validazione e statistiche. La ricerca è delegata a Predicable.
+# This concern enables managing multiple tags on models using PostgreSQL arrays
+# with normalization, validation, and statistics. Search is delegated to Predicable.
 #
-# Esempio di utilizzo:
+# @example Basic Usage
 #   class Article < ApplicationRecord
 #     include BetterModel
 #
@@ -16,18 +19,18 @@
 #     end
 #   end
 #
-# Utilizzo:
-#   article.tag_with("ruby", "rails")           # Aggiungi tag
-#   article.untag("rails")                      # Rimuovi tag
-#   article.tag_list = "ruby, rails, tutorial"  # Da stringa CSV
+# @example Managing Tags
+#   article.tag_with("ruby", "rails")           # Add tags
+#   article.untag("rails")                      # Remove tags
+#   article.tag_list = "ruby, rails, tutorial"  # From CSV string
 #   article.tagged_with?("ruby")                # => true
 #
-# Ricerca (delegata a Predicable):
+# @example Searching (Delegated to Predicable)
 #   Article.tags_contains("ruby")               # Predicable
 #   Article.tags_overlaps(["ruby", "python"])   # Predicable
 #   Article.search(tags_contains: "ruby")       # Searchable + Predicable
 #
-# Statistiche:
+# @example Statistics
 #   Article.tag_counts                          # => {"ruby" => 45, "rails" => 38}
 #   Article.popular_tags(limit: 10)             # => [["ruby", 45], ["rails", 38], ...]
 #
@@ -35,7 +38,11 @@ module BetterModel
   module Taggable
     extend ActiveSupport::Concern
 
-    # Configurazione Taggable
+    # Taggable Configuration.
+    #
+    # Internal configuration class for the Taggable DSL.
+    #
+    # @api private
     class Configuration
       attr_reader :validates_minimum, :validates_maximum, :allowed_tags, :forbidden_tags
 
@@ -91,19 +98,22 @@ module BetterModel
     end
 
     included do
-      # Valida che sia incluso solo in modelli ActiveRecord
+      # Validate ActiveRecord inheritance
       unless ancestors.include?(ActiveRecord::Base)
-        raise ArgumentError, "BetterModel::Taggable can only be included in ActiveRecord models"
+        raise BetterModel::Errors::Taggable::ConfigurationError, "Invalid configuration"
       end
 
-      # Configurazione Taggable per questa classe
+      # Taggable configuration for this class
       class_attribute :taggable_config, default: nil
     end
 
     class_methods do
-      # DSL per configurare Taggable
+      # DSL to configure Taggable.
       #
-      # Esempio:
+      # @yield [config] Configuration block
+      # @raise [BetterModel::Errors::Taggable::ConfigurationError] If already configured or field doesn't exist
+      #
+      # @example
       #   taggable do
       #     tag_field :tags
       #     normalize true
@@ -114,39 +124,41 @@ module BetterModel
       #     validates_tags minimum: 1, maximum: 10, allowed_tags: ["ruby", "rails"]
       #   end
       def taggable(&block)
-        # Previeni configurazione multipla
+        # Prevent multiple configuration
         if taggable_config.present?
-          raise ArgumentError, "Taggable already configured for #{name}"
+          raise BetterModel::Errors::Taggable::ConfigurationError, "Invalid configuration"
         end
 
-        # Crea configurazione
+        # Create configuration
         config = Configuration.new
         config.instance_eval(&block) if block_given?
 
-        # Valida che il campo esista
+        # Validate that field exists
         tag_field_name = config.tag_field.to_s
         unless column_names.include?(tag_field_name)
-          raise ArgumentError, "Tag field #{config.tag_field} does not exist in #{table_name}"
+          raise BetterModel::Errors::Taggable::ConfigurationError, "Invalid configuration"
         end
 
-        # Salva configurazione (frozen per thread-safety)
+        # Save configuration (frozen for thread-safety)
         self.taggable_config = config.freeze
 
-        # Auto-registra predicates per ricerca (delegato a Predicable)
+        # Auto-register predicates for search (delegated to Predicable)
         predicates config.tag_field if respond_to?(:predicates)
 
-        # Registra validazioni se configurate
+        # Register validations if configured
         setup_validations(config) if config.validates_minimum || config.validates_maximum ||
                                      config.allowed_tags || config.forbidden_tags
       end
 
       # ============================================================================
-      # CLASS METHODS - Statistiche
+      # CLASS METHODS - Statistics
       # ============================================================================
 
-      # Restituisce un hash con il conteggio di ciascun tag
+      # Returns a hash with the count of each tag.
+      #
+      # @return [Hash{String => Integer}] Tag counts
       #
-      # Esempio:
+      # @example
       #   Article.tag_counts  # => {"ruby" => 45, "rails" => 38, "tutorial" => 12}
       def tag_counts
         return {} unless taggable_config
@@ -163,9 +175,12 @@ module BetterModel
         counts
       end
 
-      # Restituisce i tag più popolari con il loro conteggio
+      # Returns the most popular tags with their counts.
       #
-      # Esempio:
+      # @param limit [Integer] Maximum number of tags to return
+      # @return [Array<Array(String, Integer)>] Tag-count pairs sorted by count
+      #
+      # @example
       #   Article.popular_tags(limit: 10)
       #   # => [["ruby", 45], ["rails", 38], ["tutorial", 12]]
       def popular_tags(limit: 10)
@@ -176,9 +191,13 @@ module BetterModel
           .first(limit)
       end
 
-      # Restituisce i tag che appaiono insieme al tag specificato
+      # Returns tags that appear together with the specified tag.
+      #
+      # @param tag [String] Tag to find related tags for
+      # @param limit [Integer] Maximum number of related tags to return
+      # @return [Array<String>] Related tags sorted by frequency
       #
-      # Esempio:
+      # @example
       #   Article.related_tags("ruby", limit: 10)
       #   # => ["rails", "gem", "activerecord"]
       def related_tags(tag, limit: 10)
@@ -187,25 +206,25 @@ module BetterModel
         field = taggable_config.tag_field
         related_counts = Hash.new(0)
 
-        # Normalizza il tag query
+        # Normalize query tag
         config = taggable_config
         normalized_tag = tag.to_s
         normalized_tag = normalized_tag.strip if config.strip
         normalized_tag = normalized_tag.downcase if config.normalize
 
-        # Trova record che contengono il tag
+        # Find records containing the tag
         find_each do |record|
           tags = record.public_send(field) || []
           next unless tags.include?(normalized_tag)
 
-          # Conta gli altri tag che appaiono insieme
+          # Count other tags that appear together
           tags.each do |other_tag|
             next if other_tag == normalized_tag
             related_counts[other_tag] += 1
           end
         end
 
-        # Restituisci ordinati per frequenza
+        # Return sorted by frequency
         related_counts
           .sort_by { |_tag, count| -count }
           .first(limit)
@@ -214,11 +233,14 @@ module BetterModel
 
       private
 
-      # Setup delle validazioni ActiveRecord
+      # Setup ActiveRecord validations.
+      #
+      # @param config [Configuration] Taggable configuration
+      # @api private
       def setup_validations(config)
         field = config.tag_field
 
-        # Validazione minimum
+        # Minimum validation
         if config.validates_minimum
           min = config.validates_minimum
           validate do
@@ -229,7 +251,7 @@ module BetterModel
           end
         end
 
-        # Validazione maximum
+        # Maximum validation
         if config.validates_maximum
           max = config.validates_maximum
           validate do
@@ -240,7 +262,7 @@ module BetterModel
           end
         end
 
-        # Validazione whitelist
+        # Whitelist validation
         if config.allowed_tags
           allowed = config.allowed_tags
           validate do
@@ -252,7 +274,7 @@ module BetterModel
           end
         end
 
-        # Validazione blacklist
+        # Blacklist validation
         if config.forbidden_tags
           forbidden = config.forbidden_tags
           validate do
@@ -267,12 +289,15 @@ module BetterModel
     end
 
     # ============================================================================
-    # INSTANCE METHODS - Gestione Tag
+    # INSTANCE METHODS - Tag Management
     # ============================================================================
 
-    # Aggiunge uno o più tag al record
+    # Add one or more tags to the record.
+    #
+    # @param new_tags [Array<String>] Tags to add
+    # @return [void]
     #
-    # Esempio:
+    # @example
     #   article.tag_with("ruby")
     #   article.tag_with("ruby", "rails", "tutorial")
     def tag_with(*new_tags)
@@ -281,21 +306,24 @@ module BetterModel
       config = self.class.taggable_config
       field = config.tag_field
 
-      # Inizializza array se nil
+      # Initialize array if nil
       current_tags = public_send(field) || []
 
-      # Normalizza e aggiungi tag (evita duplicati con |)
+      # Normalize and add tags (avoid duplicates with |)
       normalized_tags = new_tags.flatten.map { |tag| normalize_tag(tag) }.compact
       updated_tags = (current_tags | normalized_tags)
 
-      # Aggiorna il campo
+      # Update field
       public_send("#{field}=", updated_tags)
       save if persisted?
     end
 
-    # Rimuove uno o più tag dal record
+    # Remove one or more tags from the record.
     #
-    # Esempio:
+    # @param tags_to_remove [Array<String>] Tags to remove
+    # @return [void]
+    #
+    # @example
     #   article.untag("tutorial")
     #   article.untag("ruby", "rails")
     def untag(*tags_to_remove)
@@ -304,23 +332,26 @@ module BetterModel
       config = self.class.taggable_config
       field = config.tag_field
 
-      # Ottieni tag attuali
+      # Get current tags
       current_tags = public_send(field) || []
 
-      # Normalizza tag da rimuovere
+      # Normalize tags to remove
       normalized_tags = tags_to_remove.flatten.map { |tag| normalize_tag(tag) }.compact
 
-      # Rimuovi tag
+      # Remove tags
       updated_tags = current_tags - normalized_tags
 
-      # Aggiorna il campo
+      # Update field
       public_send("#{field}=", updated_tags)
       save if persisted?
     end
 
-    # Sostituisce tutti i tag esistenti con nuovi tag
+    # Replace all existing tags with new tags.
+    #
+    # @param new_tags [Array<String>] New tags to set
+    # @return [void]
     #
-    # Esempio:
+    # @example
     #   article.retag("python", "django")
     def retag(*new_tags)
       return unless taggable_enabled?
@@ -328,17 +359,20 @@ module BetterModel
       config = self.class.taggable_config
       field = config.tag_field
 
-      # Normalizza nuovi tag
+      # Normalize new tags
       normalized_tags = new_tags.flatten.map { |tag| normalize_tag(tag) }.compact.uniq
 
-      # Sostituisci tutti i tag
+      # Replace all tags
       public_send("#{field}=", normalized_tags)
       save if persisted?
     end
 
-    # Verifica se il record ha un determinato tag
+    # Check if record has a specific tag.
     #
-    # Esempio:
+    # @param tag [String] Tag to check
+    # @return [Boolean] true if record has the tag
+    #
+    # @example
     #   article.tagged_with?("ruby")  # => true/false
     def tagged_with?(tag)
       return false unless taggable_enabled?
@@ -356,9 +390,11 @@ module BetterModel
     # TAG LIST (CSV Interface)
     # ============================================================================
 
-    # Restituisce i tag come stringa separata da delimitatore
+    # Returns tags as a delimited string.
+    #
+    # @return [String] Tags joined by delimiter
     #
-    # Esempio:
+    # @example
     #   article.tag_list  # => "ruby, rails, tutorial"
     def tag_list
       return "" unless taggable_enabled?
@@ -369,14 +405,17 @@ module BetterModel
 
       current_tags = public_send(field) || []
 
-      # Aggiungi spazio dopo virgola per leggibilità (solo se delimiter è virgola)
+      # Add space after comma for readability (only if delimiter is comma)
       separator = delimiter == "," ? "#{delimiter} " : delimiter
       current_tags.join(separator)
     end
 
-    # Imposta i tag da una stringa separata da delimitatore
+    # Set tags from a delimited string.
     #
-    # Esempio:
+    # @param tag_string [String] Delimited tag string
+    # @return [void]
+    #
+    # @example
     #   article.tag_list = "ruby, rails, tutorial"
     def tag_list=(tag_string)
       return unless taggable_enabled?
@@ -401,25 +440,26 @@ module BetterModel
     # JSON SERIALIZATION
     # ============================================================================
 
-    # Override as_json per includere informazioni tag
+    # Override as_json to include tag information.
     #
-    # Opzioni:
-    #   include_tag_list: true    # Includi tag_list come string
-    #   include_tag_stats: true   # Includi statistiche tag
+    # @param options [Hash] Options for as_json
+    # @option options [Boolean] :include_tag_list Include tag_list as string
+    # @option options [Boolean] :include_tag_stats Include tag statistics
+    # @return [Hash] JSON representation
     #
-    # Esempio:
+    # @example
     #   article.as_json(include_tag_list: true, include_tag_stats: true)
     def as_json(options = {})
       json = super(options)
 
       return json unless taggable_enabled?
 
-      # Aggiungi tag_list se richiesto
+      # Add tag_list if requested
       if options[:include_tag_list]
         json["tag_list"] = tag_list
       end
 
-      # Aggiungi statistiche tag se richiesto
+      # Add tag statistics if requested
       if options[:include_tag_stats]
         config = self.class.taggable_config
         field = config.tag_field
@@ -436,12 +476,17 @@ module BetterModel
 
     private
 
-    # Verifica se Taggable è abilitato per questa classe
-    def taggable_enabled?
-      self.class.taggable_config.present?
-    end
+    # Check if Taggable is enabled for this class.
+    #
+    # @return [Boolean] true if enabled
+    # @api private
+    def taggable_enabled? = self.class.taggable_config.present?
 
-    # Normalizza un tag secondo la configurazione
+    # Normalize a tag according to configuration.
+    #
+    # @param tag [String] Tag to normalize
+    # @return [String, nil] Normalized tag or nil if invalid
+    # @api private
     def normalize_tag(tag)
       return nil if tag.blank?
 

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