no_fly_list 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e5fd47ff5074ba83503a9c1633bada42f7348aafb9a914d2c5f51a70820427d
-  data.tar.gz: a337a25cdce43d598fd501266ba0d99665c3adb183f994121fd201082e4e874b
+  metadata.gz: d5eef702cefcd730112adc305c5e17f8bb1c804d48fa3231d70549929a4f2ad9
+  data.tar.gz: 2f845bc5cd816a4c0899ed98f9cb9ac549c9513d5b79e7336876c39362ac72ca
 SHA512:
-  metadata.gz: a0063a48bd720527540437b156136c704bd9deea0c4985fb34a9c4a7595c3c932d3c9b13ab5b8032daf277b5e547b358b5343410bdb6bedae1e466bc081edecd
-  data.tar.gz: 2f430e49bc7a6cc8ed09b1aa5686121c8d90d2262f7a6cce48de48e208804ab77899227e2b48ace8a6b017a9147fd368136ce42b99eeaab9668361e1bf10acfc
+  metadata.gz: 4c31ab4627476af364c582db35a5176619d59f3bb96c8205c125f3219eec58c82d394c6b5cd54e8a45787b4c17b3f05bc962d32cb957e8a9befa0175757d88ad
+  data.tar.gz: 869883a8b6ffebed467494a2f97597defbc8718fd1f94d3ea33618aa31f391b716335830dd55dcb5eced81b7dbc177a3a62dfdb9db0dda408094422d2a89a2d0

data/lib/generators/no_fly_list/templates/tag_transformer.rb

@@ -3,14 +3,14 @@
 module ApplicationTagTransformer
   module_function
 
-  # @param tags [String|Array<String>]
+  # @param [String|Array<String>] tags
   def parse_tags(tags)
     tags = recreate_string(tags) if tags.is_a?(Array)
     tags.split(separator).map(&:strip)
   end
 
   # Recreate a string from an array of tags
-  # @param tags [Array<String>]
+  # @param [Array<String>] tags
   # @return [String]
   def recreate_string(tags)
     tags.join(separator)

data/lib/no_fly_list/railties/tasks.rake

@@ -1,93 +1,72 @@
-# frozen_string_literal: true
-
 namespace :no_fly_list do
-  desc "List all taggable records"
+  desc "List all models using NoFlyList::TaggableRecord with details about their tagging configurations"
   task taggable_records: :environment do
-    Rails.application.eager_load!
-    taggable_classes = ActiveRecord::Base.descendants.select do |klass|
-      klass.included_modules.any? { |mod| mod.in?([ NoFlyList::TaggableRecord ]) }
-    end
-
-    puts "Found #{taggable_classes.size} taggable classes:\n\n"
-
-    taggable_classes.each do |klass|
-      puts "Class: #{klass.name}"
+    classes = NoFlyList::TaskHelpers.find_taggable_classes
+    puts "Found #{classes.size} taggable classes:\n\n"
+
+    classes.each do |klass|
+      color = NoFlyList::TaskHelpers.adapter_color(klass)
+      puts "#{color}#{klass.name}#{NoFlyList::TaskHelpers::COLORS[:reset]}"
+      puts "  Tag Contexts: #{klass._no_fly_list&.tag_contexts&.keys&.join(', ')}"
+      puts "  Tables: #{klass.table_name}"
+      puts
     end
   end
 
-  desc "List all tag records"
+  desc "List all tag classes (both global and model-specific) with their inheritance chain"
   task tag_records: :environment do
-    Rails.application.eager_load!
-    tag_classes = ActiveRecord::Base.descendants.select do |klass|
-      klass.included_modules.any? { |mod| mod.in?([ NoFlyList::ApplicationTag, NoFlyList::TagRecord ]) }
-    end
+    classes = NoFlyList::TaskHelpers.find_tag_classes
+    puts "Found #{classes.size} tag classes:\n\n"
 
-    puts "Found #{tag_classes.size} tag classes:\n\n"
+    classes.each do |klass|
+      color = NoFlyList::TaskHelpers.adapter_color(klass)
+      type = klass.included_modules.include?(NoFlyList::ApplicationTag) ? 'Global' : 'Model-specific'
 
-    tag_classes.each do |klass|
-      puts "Class: #{klass.name}"
+      puts "#{color}#{klass.name}#{NoFlyList::TaskHelpers::COLORS[:reset]}"
+      puts "  Type: #{type}"
+      puts "  Table: #{klass.table_name}"
+      puts
     end
   end
 
-  desc "Check taggable records and their associated tables"
+  desc "Validate database schema for all taggable models"
   task check_taggable_records: :environment do
-    Rails.application.eager_load!
-    taggable_classes = ActiveRecord::Base.descendants.select do |klass|
-      klass.included_modules.any? { |mod| mod.in?([ NoFlyList::TaggableRecord ]) }
-    end
-
-    puts "Checking #{taggable_classes.size} taggable classes:\n\n"
-
-    taggable_classes.each do |klass|
-      puts "Checking Class: #{klass.name}"
-
-      # ANSI color codes
-      green = "\e[32m"
-      red = "\e[31m"
-      reset = "\e[0m"
-
-      # Check main table exists
-      begin
-        klass.table_exists?
-        puts "  #{green}✓#{reset} Main table exists: #{klass.table_name}"
-      rescue StandardError => e
-        puts "  #{red}✗#{reset} Error checking main table: #{e.message}"
-      end
-
-      # Dynamically find tag and tagging class names
-      tag_class_name = "#{klass.name}Tag"
-      tagging_class_name = "#{klass.name}::Tagging"
-
-      begin
-        tag_class = Object.const_get(tag_class_name)
-
-        # Check tags table exists
-        if tag_class.table_exists?
-          puts "  #{green}✓#{reset} Tags table exists: #{tag_class.table_name}"
+    classes = NoFlyList::TaskHelpers.find_taggable_classes
+    puts "Checking #{classes.size} taggable classes:\n\n"
+
+    classes.each do |klass|
+      color = NoFlyList::TaskHelpers.adapter_color(klass)
+      puts "Checking Class: #{color}#{klass.name}#{NoFlyList::TaskHelpers::COLORS[:reset]}"
+
+      status, message = NoFlyList::TaskHelpers.check_table(klass)
+      puts "  #{message}"
+
+      [
+        ["#{klass.name}Tag", "Tags", :tag],
+        ["#{klass.name}::Tagging", "Taggings", :tagging]
+      ].each do |class_name, type, column_type|
+        if (check_class = NoFlyList::TaskHelpers.check_class(class_name))
+          status, message = NoFlyList::TaskHelpers.check_table(check_class)
+          puts "  #{message}"
+          if status
+            puts "  #{NoFlyList::TaskHelpers.verify_columns(check_class, column_type)}"
+            puts "  #{NoFlyList::TaskHelpers.format_columns(check_class)}"
+          end
         else
-          puts "  #{red}✗#{reset} Tags table missing: #{tag_class.table_name}"
+          puts "  #{NoFlyList::TaskHelpers::colorize('✗', :red)} #{type} class not found: #{class_name}"
         end
-      rescue NameError
-        puts "  #{red}✗#{reset} Tag class not found: #{tag_class_name}"
-      rescue StandardError => e
-        puts "  #{red}✗#{reset} Error checking tag class: #{e.message}"
       end
 
-      begin
-        tagging_class = Object.const_get(tagging_class_name)
-
-        # Check taggings table exists
-        if tagging_class.table_exists?
-          puts "  #{green}✓#{reset} Taggings table exists: #{tagging_class.table_name}"
-        else
-          puts "  #{red}✗#{reset} Taggings table missing: #{tagging_class.table_name}"
+      klass._no_fly_list.tag_contexts.each do |context, config|
+        puts "\n  Context: #{context}"
+        bullet = NoFlyList::TaskHelpers::colorize('•', :green)
+        puts "  #{bullet} Tag class: #{config[:tag_class_name]}"
+        puts "  #{bullet} Tagging class: #{config[:tagging_class_name]}"
+        puts "  #{bullet} Polymorphic: #{config[:polymorphic]}"
+        if config[:polymorphic]
+          puts "  #{bullet} Required tagging columns: context, tag_id, taggable_id, taggable_type"
         end
-      rescue NameError
-        puts "  #{red}✗#{reset} Tagging class not found: #{tagging_class_name}"
-      rescue StandardError => e
-        puts "  #{red}✗#{reset} Error checking tagging class: #{e.message}"
       end
-
       puts "\n"
     end
   end

data/lib/no_fly_list/tag_record.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module NoFlyList
-  # This module provides functionality for a tag table that contains tags for a model.
+  # Provides tag table functionality for models
+  # Handles tag attributes and delegation of methods
   #
   # @example Usage
   #   class User::Tag < ApplicationRecord
@@ -11,6 +12,9 @@ module NoFlyList
     extend ActiveSupport::Concern
 
     included do
+      # @!method to_s
+      #   @return [String] String representation of tag name
+      # @!method inspect
       delegate :to_s, to: :name
       alias_attribute :tag_name, :name
       def inspect

data/lib/no_fly_list/taggable_record/configuration.rb

@@ -13,9 +13,9 @@ module NoFlyList
       module_function
 
       # Main entry point for setting up tagging functionality on a model
-      # @param taggable_klass [Class] The model class to make taggable
-      # @param contexts [Array<Symbol>] The contexts to create tags for (e.g., :tags, :colors)
-      # @param options [Hash] Configuration options for tagging behavior
+      # @param [Class] taggable_klass The model class to make taggable
+      # @param [Array<Symbol>] contexts The contexts to create tags for (e.g., :tags, :colors)
+      # @param [Hash] options Configuration options for tagging behavior
       def setup_tagging(taggable_klass, contexts, options = {})
         contexts.each do |context|
           setup = build_tag_setup(taggable_klass, context, options)

data/lib/no_fly_list/taggable_record/mutation.rb

@@ -5,6 +5,12 @@ module NoFlyList
     module Mutation
       module_function
 
+      # Defines mutation methods for tag manipulation
+      # @param setup [TagSetup] Tag setup configuration
+      # @return [void]
+      # @example Generated methods
+      #   add_tags("red, blue")    # Adds tags
+      #   remove_tags("red")       # Removes tags
       def define_mutation_methods(setup)
         context = setup.context
         taggable_klass = setup.taggable_klass

data/lib/no_fly_list/taggable_record/query.rb

@@ -5,6 +5,12 @@ module NoFlyList
     module Query
       module_function
 
+      # Defines query methods based on database adapter
+      # @param setup [TagSetup] Tag setup configuration
+      # @return [void]
+      # @see PostgresqlStrategy#define_query_methods
+      # @see MysqlStrategy#define_query_methods
+      # @see SqliteStrategy#define_query_methods
       def define_query_methods(setup)
         case setup.adapter
         when :postgresql
@@ -19,10 +25,19 @@ module NoFlyList
       module BaseStrategy
         module_function
 
+        # Performs case-insensitive column comparison
+        # @param table [Arel::Table] Database table
+        # @param column [Symbol] Column name
+        # @param values [Array<String>] Values to compare
+        # @return [Arel::Node] Query node
+        # @abstract
         def case_insensitive_where(table, column, values)
           raise NotImplementedError
         end
 
+        # Defines database-specific query methods
+        # @abstract
+        # @param setup [TagSetup] Tag setup configuration
         def define_query_methods(setup)
           raise NotImplementedError
         end

data/lib/no_fly_list/taggable_record/tag_setup.rb

@@ -2,11 +2,42 @@
 
 module NoFlyList
   module TaggableRecord
+    # Handles setup and configuration of tagging for a model
     class TagSetup
-      attr_reader :taggable_klass, :context, :transformer, :polymorphic,
-                  :restrict_to_existing, :limit, :counter_cache,
-                  :tag_class_name, :tagging_class_name, :adapter
+      # @return [Class] Model class being made taggable
+      attr_reader :taggable_klass
 
+      # @return [Symbol] Tagging context name
+      attr_reader :context
+
+      # @return [Class] Tag string transformer
+      attr_reader :transformer
+
+      # @return [Boolean] Whether tags are polymorphic
+      attr_reader :polymorphic
+
+      # @return [Boolean] Whether to restrict to existing tags
+      attr_reader :restrict_to_existing
+
+      # @return [Integer, nil] Maximum number of tags allowed
+      attr_reader :limit
+
+      # @return [Boolean] Whether to use counter cache
+      attr_reader :counter_cache
+
+      # @return [String] Name of tag class
+      attr_reader :tag_class_name
+
+      # @return [String] Name of tagging class
+      attr_reader :tagging_class_name
+
+      # @return [Symbol] Database adapter type (:postgresql, :mysql, :sqlite)
+      attr_reader :adapter
+
+      # Creates new tag setup configuration
+      # @param taggable_klass [Class] Model to configure
+      # @param context [Symbol] Tag context name
+      # @param options [Hash] Setup options
       def initialize(taggable_klass, context, options = {})
         @taggable_klass = taggable_klass
         @context = context

data/lib/no_fly_list/taggable_record.rb

@@ -4,6 +4,12 @@ module NoFlyList
   module TaggableRecord
     extend ActiveSupport::Concern
 
+    # @!attribute _no_fly_list
+    #   @return [Config] Configuration for this taggable record
+    #
+    # @!method save_tag_proxies
+    #   @api private
+    #   Saves pending tag changes before saving the record
     included do
       class_attribute :_no_fly_list, instance_writer: false
       self._no_fly_list = Config.new self
@@ -12,6 +18,9 @@ module NoFlyList
       before_validation :validate_tag_proxies
     end
 
+    # Determines if record needs saving due to tag changes
+    # @return [Boolean] True if tags have pending changes
+    # @api private
     def changed_for_autosave?
       super || tag_proxies_changed?
     end
@@ -83,6 +92,11 @@ module NoFlyList
       end
     end
 
+    # Class methods added to taggable models
+    # @!method has_tags(*contexts, **options)
+    #   Configures tagging contexts for the model
+    #   @param contexts [Array<Symbol>] Tag context names
+    #   @param options [Hash] Options for configuring tagging
     class_methods do
       def has_tags(*contexts, **options)
         contexts.each do |context|

data/lib/no_fly_list/tagging_proxy.rb

@@ -13,6 +13,13 @@ module NoFlyList
     validate :validate_limit
     validate :validate_existing_tags
 
+    # Creates a new tagging proxy
+    # @param model [ActiveRecord::Base] Model being tagged
+    # @param tag_model [Class] Tag model class
+    # @param context [Symbol] Tagging context (e.g. :colors)
+    # @param transformer [Class] Class for transforming tag strings
+    # @param restrict_to_existing [Boolean] Only allow existing tags
+    # @param limit [Integer, nil] Maximum number of tags allowed
     def initialize(model, tag_model, context,
                    transformer: ApplicationTagTransformer,
                    restrict_to_existing: false,
@@ -26,6 +33,9 @@ module NoFlyList
       @pending_changes = []
     end
 
+    # Determines if tags have changed from database state
+    # @return [Boolean] True if pending changes differ from database
+    # @api private
     def changed?
       @pending_changes.present? && @pending_changes != current_list_from_database
     end
@@ -50,6 +60,9 @@ module NoFlyList
         method_name.to_s =~ /\A(.+)_list(=)?\z/
     end
 
+    # Handles numeric coercion
+    # @param other [Object] Object to coerce with
+    # @return [Array] Two-element array for coercion
     def coerce(other)
       [ other, to_a ]
     end
@@ -152,10 +165,20 @@ module NoFlyList
       "#<#{self.class.name} tags=#{current_list.inspect} transformer_with=#{transformer_name} >"
     end
 
+    # Adds one or more tags to the current tag list
+    # @param *tags [Array<String, Array<String>>] Tags to add:
+    #   - Single string with comma-separated values ("tag1, tag2")
+    #   - Single array of strings (["tag1", "tag2"])
+    #   - Multiple string arguments ("tag1", "tag2")
+    # @return [TaggingProxy] Returns self for method chaining
     def add(*tags)
       return self if limit_reached?
 
-      new_tags = tags.flatten.map { |tag| transformer.parse_tags(tag) }.flatten
+      new_tags = if tags.size == 1 && tags.first.is_a?(String)
+                   transformer.parse_tags(tags.first)
+      else
+                   tags.flatten.map { |tag| transformer.parse_tags(tag) }.flatten
+      end
       return self if new_tags.empty?
 
       @pending_changes = current_list + new_tags
@@ -168,9 +191,21 @@ module NoFlyList
       save
     end
 
-    def remove(tag)
+    # Removes one or more tags from the current tag list
+    # @param *tags [Array<String, Array<String>>] Tags to remove:
+    #   - Single string with comma-separated values ("tag1, tag2")
+    #   - Single array of strings (["tag1", "tag2"])
+    #   - Multiple string arguments ("tag1", "tag2")
+    # @return [TaggingProxy] Returns self for method chaining
+    # @raise [ActiveRecord::RecordInvalid] If validation fails
+    def remove(*tags)
       old_list = current_list.dup
-      @pending_changes = current_list - [ tag.to_s.strip ]
+      tags_to_remove = if tags.size == 1 && tags.first.is_a?(String)
+                         transformer.parse_tags(tags.first)
+      else
+                         tags.flatten.map { |tag| tag.to_s.strip }
+      end
+      @pending_changes = current_list - tags_to_remove
       mark_record_dirty if @pending_changes != old_list
       self
     end
@@ -180,6 +215,10 @@ module NoFlyList
       save
     end
 
+    # Clears all tags
+    # @return [TaggingProxy] Returns self for method chaining
+    # @example Clear all tags
+    #   tags.clear #=> []
     def clear
       old_list = current_list.dup
       @pending_changes = []
@@ -188,6 +227,11 @@ module NoFlyList
       self
     end
 
+    # Forces clearing all tags by destroying records
+    # @return [TaggingProxy] Returns self for method chaining
+    # @example Force clear tags
+    #   tags.clear! #=> []
+    # @raise [ActiveRecord::RecordNotDestroyed] If destroy fails
     def clear!
       @model.send(@context.to_s).destroy_all
       @pending_changes = []
@@ -195,14 +239,23 @@ module NoFlyList
       self
     end
 
+    # Checks if a tag exists in the list
+    # @param tag [String] Tag to check for
+    # @return [Boolean] True if tag exists
     def include?(tag)
       current_list.include?(tag.to_s.strip)
     end
 
+    # Checks if tag list is empty
+    # @return [Boolean] True if no tags exist
     def empty?
       current_list.empty?
     end
 
+    # Required by ActiveModel::Validations
+    # @return [Boolean] Always returns false since proxy isn't persisted
+    # @api private
+    # @see https://api.rubyonrails.org/classes/ActiveModel/Validations.html
     def persisted?
       false
     end

data/lib/no_fly_list/task_helpers.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module NoFlyList
+  module TaskHelpers
+    COLORS = {
+      mysql2: "\e[38;5;33m",
+      postgresql: "\e[38;5;31m",
+      sqlite: "\e[38;5;245m",
+      reset: "\e[0m",
+      green: "\e[32m",
+      red: "\e[31m",
+      yellow: "\e[33m"
+    }.freeze
+
+    REQUIRED_COLUMNS = {
+      tag: ['name'],
+      tagging: ['tag_id', 'taggable_id', 'context']
+    }.freeze
+
+    def self.adapter_color(klass)
+      color_key = klass.connection.adapter_name.downcase.to_sym
+      COLORS[color_key] || COLORS[:sqlite]
+    end
+
+    def self.colorize(text, color)
+      "#{COLORS[color]}#{text}#{COLORS[:reset]}"
+    end
+
+    def self.check_table(klass)
+      klass.table_exists?
+      [true, "#{colorize('✓', :green)} Table exists: #{klass.table_name}"]
+    rescue StandardError => e
+      [false, "#{colorize('✗', :red)} Error: #{e.message}"]
+    end
+
+    def self.verify_columns(klass, type)
+      return unless klass.table_exists?
+
+      existing_columns = klass.column_names
+      required_columns = REQUIRED_COLUMNS[type]
+      missing_columns = required_columns - existing_columns
+
+      if missing_columns.empty?
+        "#{colorize('✓', :green)} Required columns present"
+      else
+        "#{colorize('!', :yellow)} Missing required columns: #{missing_columns.join(', ')}"
+      end
+    end
+
+    def self.format_columns(klass)
+      return unless klass.table_exists?
+      "#{colorize('✓', :green)} All columns: #{klass.column_names.join(', ')}"
+    end
+
+    def self.check_class(class_name)
+      Object.const_get(class_name)
+    rescue NameError
+      nil
+    end
+
+    def self.find_taggable_classes
+      Rails.application.eager_load!
+      ActiveRecord::Base.descendants.select do |klass|
+        klass.included_modules.any? { |mod| mod.in?([NoFlyList::TaggableRecord]) }
+      end
+    end
+
+    def self.find_tag_classes
+      Rails.application.eager_load!
+      ActiveRecord::Base.descendants.select do |klass|
+        klass.included_modules.any? { |mod| mod.in?([NoFlyList::ApplicationTag, NoFlyList::TagRecord]) }
+      end
+    end
+  end
+end
+

data/lib/no_fly_list/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NoFlyList
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/no_fly_list.rb

@@ -32,4 +32,5 @@ module NoFlyList
   autoload :TaggingProxy
 
   autoload :TestHelper
+  autoload :TaskHelpers
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: no_fly_list
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Abdelkader Boudih
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-19 00:00:00.000000000 Z
+date: 2024-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -59,6 +59,7 @@ files:
 - lib/no_fly_list/taggable_record/tag_setup.rb
 - lib/no_fly_list/tagging_proxy.rb
 - lib/no_fly_list/tagging_record.rb
+- lib/no_fly_list/task_helpers.rb
 - lib/no_fly_list/test_helper.rb
 - lib/no_fly_list/version.rb
 homepage: https://github.com/contriboss/no_fly_list