better_model 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec236d26e4c1e0a5a62e9932606a1baa28de1bcadf8b447f1da545fb35d029b6
-  data.tar.gz: 24e4aa004924ab09c6104cad770229041b8c8d24556ce5f2f2d190bf15071e90
+  metadata.gz: 93cc27ca4bb13c22c5d3ac1f0aa96010f7377bf687805b5f76bee89d44b83f5f
+  data.tar.gz: 5234fde47b3b13fc0ccc2da3fc3948f094ccd0f7eaa2cb4d8d219e6cf291a1c3
 SHA512:
-  metadata.gz: 77d291e54bcbbb179eabd842290530d0f42e03636981e93bfdeb6575d5d0e02960d359072c0b0db0144f35cdbea647d463bf7320037c557552f6fce8365a393e
-  data.tar.gz: bfe3bf61206cb343dce4d84b2ff643e719c09b93a623de77e127a00aadbce646d25bfcc2cd66ca3bd725b6af224a82eb7cff2e059f79f45c8e026d5d878c95d6
+  metadata.gz: 3f9394cdc2201586b8b1d510d60aa286d29a86ab1a0c313f61401b850545a1924b08b16489b446d786aac38aa919ff7546dd6e3d3d5c9a9ca8a310b74ecbddc0
+  data.tar.gz: 8f218e1eb37bc94cb8510cda0ae32033458b1befe2ff5012a766b7c9874865b63b90facb72d7ba97deb1b80175fef06dbf27f6e42b2b9d44d3f47e212908cc7e

data/README.md

@@ -104,6 +104,17 @@ class Article < ApplicationRecord
     default_order [:sort_published_at_desc]
     security :status_required, [:status_eq]
   end
+
+  # 10. TAGGABLE - Tag management with statistics (opt-in)
+  taggable do
+    tag_field :tags
+    normalize true         # Automatic lowercase
+    strip true             # Remove whitespace
+    min_length 2           # Minimum tag length
+    max_length 30          # Maximum tag length
+    delimiter ","          # CSV delimiter
+    validates_tags minimum: 1, maximum: 10
+  end
 end
 ```
 
@@ -172,6 +183,22 @@ Article.search(
   orders: [:sort_published_at_desc],
   pagination: { page: 1, per_page: 25 }
 )
+
+# 🏷️ Manage tags
+article.tag_with("ruby", "rails", "tutorial")
+article.untag("tutorial")
+article.tagged_with?("ruby")  # => true
+article.tag_list = "ruby, rails, api"
+
+# 📊 Query with tags (via Predicable)
+Article.tags_contains("ruby")
+Article.tags_overlaps(["ruby", "python"])
+Article.tags_contains_all(["ruby", "rails"])
+
+# 📈 Tag statistics
+Article.tag_counts                    # => {"ruby" => 45, "rails" => 38}
+Article.popular_tags(limit: 10)       # => [["ruby", 45], ["rails", 38]]
+Article.related_tags("ruby", limit: 5)  # => ["rails", "gem", "tutorial"]
 ```
 
 ### 🎯 Including Individual Concerns (Advanced)
@@ -189,6 +216,7 @@ class Article < ApplicationRecord
   include BetterModel::Validatable   # Only validations
   include BetterModel::Stateable     # Only state machine
   include BetterModel::Searchable    # Only search (requires Predicable & Sortable)
+  include BetterModel::Taggable      # Only tag management
 
   # Define your features...
 end
@@ -196,19 +224,20 @@ end
 
 ## 📋 Features Overview
 
-BetterModel provides nine powerful concerns that work seamlessly together:
+BetterModel provides ten powerful concerns that work seamlessly together:
 
 ### Core Features
 
 - **✨ Statusable** - Declarative status management with lambda-based conditions
 - **🔐 Permissible** - State-based permission system
 - **🗄️ Archivable** - Soft delete with tracking (by user, reason)
-- **⏰ Traceable** 🆕 - Complete audit trail with time-travel and rollback
+- **⏰ Traceable** - Complete audit trail with time-travel and rollback
 - **⬆️ Sortable** - Type-aware sorting scopes
 - **🔍 Predicable** - Advanced filtering with rich predicate system
 - **🔎 Searchable** - Unified search interface (Predicable + Sortable)
 - **✅ Validatable** - Declarative validation DSL with conditional rules
-- **🔄 Stateable** 🆕 - Declarative state machines with guards & callbacks
+- **🔄 Stateable** - Declarative state machines with guards & callbacks
+- **🏷️ Taggable** 🆕 - Tag management with normalization, validation, and statistics
 
 [See all features in detail →](#-features)
 
@@ -391,6 +420,24 @@ Orchestrate Predicable and Sortable into a powerful, secure search interface wit
 
 ---
 
+### 🏷️ Taggable - Tag Management with Statistics
+
+Manage tags with automatic normalization, validation, and comprehensive statistics - integrated with Predicable for powerful searches.
+
+**🎯 Key Benefits:**
+- 🎛️ Opt-in activation: only enabled when explicitly configured
+- 🤖 Automatic normalization (lowercase, strip, length limits)
+- ✅ Validation (min/max count, whitelist, blacklist)
+- 📊 Statistics (tag counts, popularity, co-occurrence)
+- 🔍 Automatic Predicable integration for searches
+- 📝 CSV import/export with tag_list
+- 🐘 PostgreSQL arrays or serialized JSON for SQLite
+- 🎯 Thread-safe configuration
+
+**[📖 Full Documentation →](docs/taggable.md)** | **[📚 Examples →](docs/examples/11_taggable.md)**
+
+---
+
 ### 📜 Traceable - Audit Trail & Change Tracking
 
 Track all changes to your records with comprehensive audit trail functionality, time-travel queries, and rollback capabilities.
@@ -532,9 +579,7 @@ article.update!(title: "Corrected Title")
 
 ---
 
-## 📌 Version & Changelog
-
-**Current Version:** 1.0.0
+## 📌 Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
 
@@ -623,12 +668,13 @@ bundle exec rubocop
 
 ### 📊 Test Coverage Notes
 
-The test suite runs on **SQLite** for performance and portability. Current coverage: **91.45%** (1272 / 1391 lines).
+The test suite runs on **SQLite** for performance and portability. Current coverage: **92.57%** (1507 / 1628 lines).
 
 **Database-Specific Features Not Covered:**
-- **Predicable**: PostgreSQL array predicates (`_overlaps`, `_contains`, `_contained_by`) and JSONB predicates (`_has_key`, `_has_any_key`, `_has_all_keys`, `_jsonb_contains`) - lines 278-376 in `lib/better_model/predicable.rb`
-- **Traceable**: PostgreSQL JSONB queries and MySQL JSON_EXTRACT queries for field-specific change tracking - lines 454-489 in `lib/better_model/traceable.rb`
-- **Sortable**: MySQL NULLS emulation with CASE statements - lines 198-203 in `lib/better_model/sortable.rb`
+- **Predicable**: PostgreSQL array predicates (`_overlaps`, `_contains`, `_contained_by`) and JSONB predicates (`_has_key`, `_has_any_key`, `_has_all_keys`, `_jsonb_contains`)
+- **Traceable**: PostgreSQL JSONB queries and MySQL JSON_EXTRACT queries for field-specific change tracking
+- **Sortable**: MySQL NULLS emulation with CASE statements
+- **Taggable**: PostgreSQL native array operations (covered by Predicable tests)
 
 These features are fully implemented with proper SQL sanitization but require manual testing on PostgreSQL/MySQL:
 

data/lib/better_model/taggable.rb

@@ -0,0 +1,466 @@
+# frozen_string_literal: true
+
+# Taggable - Sistema di gestione tag dichiarativo per modelli Rails
+#
+# Questo concern permette di gestire tag multipli sui modelli utilizzando array PostgreSQL
+# con normalizzazione, validazione e statistiche. La ricerca è delegata a Predicable.
+#
+# Esempio di utilizzo:
+#   class Article < ApplicationRecord
+#     include BetterModel
+#
+#     taggable do
+#       tag_field :tags
+#       normalize true
+#       validates_tags minimum: 1, maximum: 10
+#     end
+#   end
+#
+# Utilizzo:
+#   article.tag_with("ruby", "rails")           # Aggiungi tag
+#   article.untag("rails")                      # Rimuovi tag
+#   article.tag_list = "ruby, rails, tutorial"  # Da stringa CSV
+#   article.tagged_with?("ruby")                # => true
+#
+# Ricerca (delegata a Predicable):
+#   Article.tags_contains("ruby")               # Predicable
+#   Article.tags_overlaps(["ruby", "python"])   # Predicable
+#   Article.search(tags_contains: "ruby")       # Searchable + Predicable
+#
+# Statistiche:
+#   Article.tag_counts                          # => {"ruby" => 45, "rails" => 38}
+#   Article.popular_tags(limit: 10)             # => [["ruby", 45], ["rails", 38], ...]
+#
+module BetterModel
+  module Taggable
+    extend ActiveSupport::Concern
+
+    # Configurazione Taggable
+    class Configuration
+      attr_reader :validates_minimum, :validates_maximum, :allowed_tags, :forbidden_tags
+
+      def initialize
+        @tag_field = :tags
+        @normalize = false
+        @strip = true
+        @min_length = nil
+        @max_length = nil
+        @delimiter = ","
+        @validates_minimum = nil
+        @validates_maximum = nil
+        @allowed_tags = nil
+        @forbidden_tags = nil
+      end
+
+      def tag_field(field_name = nil)
+        return @tag_field if field_name.nil?
+        @tag_field = field_name.to_sym
+      end
+
+      def normalize(value = nil)
+        return @normalize if value.nil?
+        @normalize = value
+      end
+
+      def strip(value = nil)
+        return @strip if value.nil?
+        @strip = value
+      end
+
+      def min_length(value = nil)
+        return @min_length if value.nil?
+        @min_length = value
+      end
+
+      def max_length(value = nil)
+        return @max_length if value.nil?
+        @max_length = value
+      end
+
+      def delimiter(value = nil)
+        return @delimiter if value.nil?
+        @delimiter = value
+      end
+
+      def validates_tags(options = {})
+        @validates_minimum = options[:minimum]
+        @validates_maximum = options[:maximum]
+        @allowed_tags = Array(options[:allowed_tags]) if options[:allowed_tags]
+        @forbidden_tags = Array(options[:forbidden_tags]) if options[:forbidden_tags]
+      end
+    end
+
+    included do
+      # Valida che sia incluso solo in modelli ActiveRecord
+      unless ancestors.include?(ActiveRecord::Base)
+        raise ArgumentError, "BetterModel::Taggable can only be included in ActiveRecord models"
+      end
+
+      # Configurazione Taggable per questa classe
+      class_attribute :taggable_config, default: nil
+    end
+
+    class_methods do
+      # DSL per configurare Taggable
+      #
+      # Esempio:
+      #   taggable do
+      #     tag_field :tags
+      #     normalize true
+      #     strip true
+      #     min_length 2
+      #     max_length 50
+      #     delimiter ','
+      #     validates_tags minimum: 1, maximum: 10, allowed_tags: ["ruby", "rails"]
+      #   end
+      def taggable(&block)
+        # Previeni configurazione multipla
+        if taggable_config.present?
+          raise ArgumentError, "Taggable already configured for #{name}"
+        end
+
+        # Crea configurazione
+        config = Configuration.new
+        config.instance_eval(&block) if block_given?
+
+        # Valida che il campo esista
+        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}"
+        end
+
+        # Salva configurazione (frozen per thread-safety)
+        self.taggable_config = config.freeze
+
+        # Auto-registra predicates per ricerca (delegato a Predicable)
+        predicates config.tag_field if respond_to?(:predicates)
+
+        # Registra validazioni se configurate
+        setup_validations(config) if config.validates_minimum || config.validates_maximum ||
+                                     config.allowed_tags || config.forbidden_tags
+      end
+
+      # ============================================================================
+      # CLASS METHODS - Statistiche
+      # ============================================================================
+
+      # Restituisce un hash con il conteggio di ciascun tag
+      #
+      # Esempio:
+      #   Article.tag_counts  # => {"ruby" => 45, "rails" => 38, "tutorial" => 12}
+      def tag_counts
+        return {} unless taggable_config
+
+        field = taggable_config.tag_field
+        counts = Hash.new(0)
+
+        # Itera tutti i record e conta i tag
+        find_each do |record|
+          tags = record.public_send(field) || []
+          tags.each { |tag| counts[tag] += 1 }
+        end
+
+        counts
+      end
+
+      # Restituisce i tag più popolari con il loro conteggio
+      #
+      # Esempio:
+      #   Article.popular_tags(limit: 10)
+      #   # => [["ruby", 45], ["rails", 38], ["tutorial", 12]]
+      def popular_tags(limit: 10)
+        return [] unless taggable_config
+
+        tag_counts
+          .sort_by { |_tag, count| -count }
+          .first(limit)
+      end
+
+      # Restituisce i tag che appaiono insieme al tag specificato
+      #
+      # Esempio:
+      #   Article.related_tags("ruby", limit: 10)
+      #   # => ["rails", "gem", "activerecord"]
+      def related_tags(tag, limit: 10)
+        return [] unless taggable_config
+
+        field = taggable_config.tag_field
+        related_counts = Hash.new(0)
+
+        # Normalizza il tag query
+        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_each do |record|
+          tags = record.public_send(field) || []
+          next unless tags.include?(normalized_tag)
+
+          # Conta gli altri tag che appaiono insieme
+          tags.each do |other_tag|
+            next if other_tag == normalized_tag
+            related_counts[other_tag] += 1
+          end
+        end
+
+        # Restituisci ordinati per frequenza
+        related_counts
+          .sort_by { |_tag, count| -count }
+          .first(limit)
+          .map(&:first)
+      end
+
+      private
+
+      # Setup delle validazioni ActiveRecord
+      def setup_validations(config)
+        field = config.tag_field
+
+        # Validazione minimum
+        if config.validates_minimum
+          min = config.validates_minimum
+          validate do
+            tags = public_send(field) || []
+            if tags.size < min
+              errors.add(field, "must have at least #{min} tags")
+            end
+          end
+        end
+
+        # Validazione maximum
+        if config.validates_maximum
+          max = config.validates_maximum
+          validate do
+            tags = public_send(field) || []
+            if tags.size > max
+              errors.add(field, "must have at most #{max} tags")
+            end
+          end
+        end
+
+        # Validazione whitelist
+        if config.allowed_tags
+          allowed = config.allowed_tags
+          validate do
+            tags = public_send(field) || []
+            invalid_tags = tags - allowed
+            if invalid_tags.any?
+              errors.add(field, "contains invalid tags: #{invalid_tags.join(', ')}")
+            end
+          end
+        end
+
+        # Validazione blacklist
+        if config.forbidden_tags
+          forbidden = config.forbidden_tags
+          validate do
+            tags = public_send(field) || []
+            forbidden_found = tags & forbidden
+            if forbidden_found.any?
+              errors.add(field, "contains forbidden tags: #{forbidden_found.join(', ')}")
+            end
+          end
+        end
+      end
+    end
+
+    # ============================================================================
+    # INSTANCE METHODS - Gestione Tag
+    # ============================================================================
+
+    # Aggiunge uno o più tag al record
+    #
+    # Esempio:
+    #   article.tag_with("ruby")
+    #   article.tag_with("ruby", "rails", "tutorial")
+    def tag_with(*new_tags)
+      return unless taggable_enabled?
+
+      config = self.class.taggable_config
+      field = config.tag_field
+
+      # Inizializza array se nil
+      current_tags = public_send(field) || []
+
+      # Normalizza e aggiungi tag (evita duplicati con |)
+      normalized_tags = new_tags.flatten.map { |tag| normalize_tag(tag) }.compact
+      updated_tags = (current_tags | normalized_tags)
+
+      # Aggiorna il campo
+      public_send("#{field}=", updated_tags)
+      save if persisted?
+    end
+
+    # Rimuove uno o più tag dal record
+    #
+    # Esempio:
+    #   article.untag("tutorial")
+    #   article.untag("ruby", "rails")
+    def untag(*tags_to_remove)
+      return unless taggable_enabled?
+
+      config = self.class.taggable_config
+      field = config.tag_field
+
+      # Ottieni tag attuali
+      current_tags = public_send(field) || []
+
+      # Normalizza tag da rimuovere
+      normalized_tags = tags_to_remove.flatten.map { |tag| normalize_tag(tag) }.compact
+
+      # Rimuovi tag
+      updated_tags = current_tags - normalized_tags
+
+      # Aggiorna il campo
+      public_send("#{field}=", updated_tags)
+      save if persisted?
+    end
+
+    # Sostituisce tutti i tag esistenti con nuovi tag
+    #
+    # Esempio:
+    #   article.retag("python", "django")
+    def retag(*new_tags)
+      return unless taggable_enabled?
+
+      config = self.class.taggable_config
+      field = config.tag_field
+
+      # Normalizza nuovi tag
+      normalized_tags = new_tags.flatten.map { |tag| normalize_tag(tag) }.compact.uniq
+
+      # Sostituisci tutti i tag
+      public_send("#{field}=", normalized_tags)
+      save if persisted?
+    end
+
+    # Verifica se il record ha un determinato tag
+    #
+    # Esempio:
+    #   article.tagged_with?("ruby")  # => true/false
+    def tagged_with?(tag)
+      return false unless taggable_enabled?
+
+      config = self.class.taggable_config
+      field = config.tag_field
+
+      current_tags = public_send(field) || []
+      normalized_tag = normalize_tag(tag)
+
+      current_tags.include?(normalized_tag)
+    end
+
+    # ============================================================================
+    # TAG LIST (CSV Interface)
+    # ============================================================================
+
+    # Restituisce i tag come stringa separata da delimitatore
+    #
+    # Esempio:
+    #   article.tag_list  # => "ruby, rails, tutorial"
+    def tag_list
+      return "" unless taggable_enabled?
+
+      config = self.class.taggable_config
+      field = config.tag_field
+      delimiter = config.delimiter
+
+      current_tags = public_send(field) || []
+
+      # Aggiungi spazio dopo virgola per leggibilità (solo se delimiter è virgola)
+      separator = delimiter == "," ? "#{delimiter} " : delimiter
+      current_tags.join(separator)
+    end
+
+    # Imposta i tag da una stringa separata da delimitatore
+    #
+    # Esempio:
+    #   article.tag_list = "ruby, rails, tutorial"
+    def tag_list=(tag_string)
+      return unless taggable_enabled?
+
+      config = self.class.taggable_config
+      field = config.tag_field
+      delimiter = config.delimiter
+
+      # Parse string
+      if tag_string.blank?
+        tags = []
+      else
+        tags = tag_string.split(delimiter).map { |tag| normalize_tag(tag) }.compact.uniq
+      end
+
+      # Imposta tags
+      public_send("#{field}=", tags)
+      save if persisted?
+    end
+
+    # ============================================================================
+    # JSON SERIALIZATION
+    # ============================================================================
+
+    # Override as_json per includere informazioni tag
+    #
+    # Opzioni:
+    #   include_tag_list: true    # Includi tag_list come string
+    #   include_tag_stats: true   # Includi statistiche tag
+    #
+    # Esempio:
+    #   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
+      if options[:include_tag_list]
+        json["tag_list"] = tag_list
+      end
+
+      # Aggiungi statistiche tag se richiesto
+      if options[:include_tag_stats]
+        config = self.class.taggable_config
+        field = config.tag_field
+        tags = public_send(field) || []
+
+        json["tag_stats"] = {
+          "count" => tags.size,
+          "tags" => tags
+        }
+      end
+
+      json
+    end
+
+    private
+
+    # Verifica se Taggable è abilitato per questa classe
+    def taggable_enabled?
+      self.class.taggable_config.present?
+    end
+
+    # Normalizza un tag secondo la configurazione
+    def normalize_tag(tag)
+      return nil if tag.blank?
+
+      config = self.class.taggable_config
+      normalized = tag.to_s
+
+      # Strip whitespace
+      normalized = normalized.strip if config.strip
+
+      # Lowercase
+      normalized = normalized.downcase if config.normalize
+
+      # Min length
+      return nil if config.min_length && normalized.length < config.min_length
+
+      # Max length
+      normalized = normalized[0...config.max_length] if config.max_length && normalized.length > config.max_length
+
+      normalized
+    end
+  end
+end

data/lib/better_model/traceable.rb

@@ -66,6 +66,7 @@ module BetterModel
       class_attribute :traceable_enabled, default: false
       class_attribute :traceable_config, default: {}.freeze
       class_attribute :traceable_fields, default: [].freeze
+      class_attribute :traceable_sensitive_fields, default: {}.freeze
       class_attribute :traceable_table_name, default: nil
       class_attribute :_traceable_setup_done, default: false
     end
@@ -88,6 +89,7 @@ module BetterModel
           configurator.instance_eval(&block)
           self.traceable_config = configurator.to_h.freeze
           self.traceable_fields = configurator.fields.freeze
+          self.traceable_sensitive_fields = configurator.sensitive_fields.freeze
           self.traceable_table_name = configurator.table_name
         end
 
@@ -282,7 +284,7 @@ module BetterModel
     # @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)
+    def rollback_to(version, updated_by_id: nil, updated_reason: nil, allow_sensitive: false)
       raise NotEnabledError unless self.class.traceable_enabled?
 
       version = versions.find(version) if version.is_a?(Integer)
@@ -292,8 +294,23 @@ module BetterModel
 
       # Apply changes from version
       if version.object_changes
-        version.object_changes.each do |field, (before_value, _after_value)|
-          send("#{field}=", before_value) if respond_to?("#{field}=")
+        version.object_changes.each do |field, (before_value, after_value)|
+          field_sym = field.to_sym
+
+          # Check if field is sensitive
+          if self.class.traceable_sensitive_fields.key?(field_sym)
+            unless allow_sensitive
+              Rails.logger.warn "[BetterModel::Traceable] Skipping sensitive field '#{field}' in rollback. Use allow_sensitive: true to rollback sensitive fields."
+              next
+            end
+
+            Rails.logger.warn "[BetterModel::Traceable] Rolling back sensitive field '#{field}' - allowed by allow_sensitive flag"
+          end
+
+          # For 'created' events, use after_value (the value at creation)
+          # For 'updated' events, use before_value (the value before the update)
+          rollback_value = version.event == "created" ? after_value : before_value
+          send("#{field}=", rollback_value) if respond_to?("#{field}=")
         end
       end
 
@@ -350,20 +367,104 @@ module BetterModel
     def tracked_changes
       return {} if self.class.traceable_fields.empty?
 
-      if saved_changes.any?
+      raw_changes = if saved_changes.any?
         # After save: use saved_changes
         saved_changes.slice(*self.class.traceable_fields.map(&:to_s))
       else
         # Before save: use changes
         changes.slice(*self.class.traceable_fields.map(&:to_s))
       end
+
+      # Apply redaction to sensitive fields
+      apply_redaction_to_changes(raw_changes)
     end
 
     # Get final state for destroyed records
     def tracked_final_state
-      self.class.traceable_fields.each_with_object({}) do |field, hash|
+      raw_state = self.class.traceable_fields.each_with_object({}) do |field, hash|
         hash[field.to_s] = [ send(field), nil ]
       end
+
+      # Apply redaction to sensitive fields
+      apply_redaction_to_changes(raw_state)
+    end
+
+    # Apply redaction to changes hash based on sensitive field configuration
+    #
+    # @param changes_hash [Hash] Hash of field changes {field => [old, new]}
+    # @return [Hash] Redacted changes hash
+    def apply_redaction_to_changes(changes_hash)
+      return changes_hash if self.class.traceable_sensitive_fields.empty?
+
+      changes_hash.each_with_object({}) do |(field, values), result|
+        field_sym = field.to_sym
+
+        if self.class.traceable_sensitive_fields.key?(field_sym)
+          level = self.class.traceable_sensitive_fields[field_sym]
+          result[field] = [
+            redact_value(field_sym, values[0], level),
+            redact_value(field_sym, values[1], level)
+          ]
+        else
+          result[field] = values
+        end
+      end
+    end
+
+    # Redact a single value based on sensitivity level
+    #
+    # @param field [Symbol] Field name
+    # @param value [Object] Value to redact
+    # @param level [Symbol] Sensitivity level (:full, :partial, :hash)
+    # @return [String] Redacted value
+    def redact_value(field, value, level)
+      return "[REDACTED]" if value.nil? && level == :full
+
+      case level
+      when :full
+        "[REDACTED]"
+      when :partial
+        redact_partial(field, value)
+      when :hash
+        require "digest"
+        "sha256:#{Digest::SHA256.hexdigest(value.to_s)}"
+      else
+        value  # Fallback to original value
+      end
+    end
+
+    # Partially redact a value based on field patterns
+    #
+    # @param field [Symbol] Field name
+    # @param value [Object] Value to partially redact
+    # @return [String] Partially redacted value
+    def redact_partial(field, value)
+      return "[REDACTED]" if value.blank?
+
+      str = value.to_s
+
+      # Credit card pattern (13-19 digits)
+      if str.gsub(/\D/, "").match?(/^\d{13,19}$/)
+        digits = str.gsub(/\D/, "")
+        "****#{digits[-4..-1]}"
+      # Email pattern
+      elsif str.include?("@")
+        parts = str.split("@")
+        username_length = parts.first.length
+        masked_username = username_length <= 3 ? "***" : "#{parts.first[0]}***"
+        "#{masked_username}@#{parts.last}"
+      # SSN pattern (US: XXX-XX-XXXX or XXXXXXXXX)
+      elsif str.gsub(/\D/, "").match?(/^\d{9}$/)
+        digits = str.gsub(/\D/, "")
+        "***-**-#{digits[-4..-1]}"
+      # Phone pattern (10+ digits)
+      elsif str.gsub(/\D/, "").match?(/^\d{10,}$/)
+        digits = str.gsub(/\D/, "")
+        "***-***-#{digits[-4..-1]}"
+      # Default: show only length
+      else
+        "[REDACTED:#{str.length}chars]"
+      end
     end
 
     # Create a version record
@@ -388,19 +489,32 @@ module BetterModel
 
   # Configurator per traceable DSL
   class TraceableConfigurator
-    attr_reader :fields, :table_name
+    attr_reader :fields, :table_name, :sensitive_fields
 
     def initialize(model_class)
       @model_class = model_class
       @fields = []
+      @sensitive_fields = {}
       @table_name = nil
     end
 
     # Specify which fields to track
     #
     # @param field_names [Array<Symbol>] Field names to track
-    def track(*field_names)
-      @fields.concat(field_names)
+    # @param sensitive [Symbol, nil] Sensitivity level (:full, :partial, :hash)
+    #
+    # @example Normal tracking
+    #   track :title, :status
+    #
+    # @example Sensitive tracking
+    #   track :password, sensitive: :full
+    #   track :email, sensitive: :partial
+    #   track :ssn, sensitive: :hash
+    def track(*field_names, sensitive: nil)
+      field_names.each do |field|
+        @fields << field
+        @sensitive_fields[field] = sensitive if sensitive
+      end
     end
 
     # Specify custom table name for versions
@@ -411,7 +525,7 @@ module BetterModel
     end
 
     def to_h
-      { fields: @fields, table_name: @table_name }
+      { fields: @fields, sensitive_fields: @sensitive_fields, table_name: @table_name }
     end
   end
 

data/lib/better_model/version.rb

@@ -1,3 +1,3 @@
 module BetterModel
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/better_model/version_record.rb

@@ -45,11 +45,14 @@ module BetterModel
       }
     end
 
-    # Check if a specific field changed
+    # Check if a specific field changed in this version
+    # This method overrides ActiveRecord's changed? to accept a field_name parameter
     #
-    # @param field_name [Symbol, String] Field name
+    # @param field_name [Symbol, String, nil] Field name (if nil, calls ActiveRecord's changed?)
     # @return [Boolean]
-    def changed?(field_name)
+    def changed?(field_name = nil)
+      return super() if field_name.nil?
+
       object_changes&.key?(field_name.to_s) || false
     end
 

data/lib/better_model.rb

@@ -18,6 +18,7 @@ require "better_model/stateable/configurator"
 require "better_model/stateable/errors"
 require "better_model/stateable/guard"
 require "better_model/stateable/transition"
+require "better_model/taggable"
 
 module BetterModel
   extend ActiveSupport::Concern
@@ -33,5 +34,6 @@ module BetterModel
     include BetterModel::Traceable
     include BetterModel::Validatable
     include BetterModel::Stateable
+    include BetterModel::Taggable
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: better_model
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - alessiobussolari
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-30 00:00:00.000000000 Z
+date: 2025-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -55,6 +55,7 @@ files:
 - lib/better_model/stateable/guard.rb
 - lib/better_model/stateable/transition.rb
 - lib/better_model/statusable.rb
+- lib/better_model/taggable.rb
 - lib/better_model/traceable.rb
 - lib/better_model/validatable.rb
 - lib/better_model/validatable/business_rule_validator.rb