dynamic-active-model 0.6.1 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a37ad8867ebc7255e83cbb62c1a70e3394e77db96e230afb669352cd4d68643e
-  data.tar.gz: 7fd3f802d8cae2c9bb59856d3cbd0a71c94977b76dc53ee69471b1eb0718fb3c
+  metadata.gz: 14a04d1dd0784f4300e46dd358b5ad392cac0f1244b6a7520465df06ae2bb84a
+  data.tar.gz: ad0cf1bda6db17ee7354d64c24dc42cd9330f8404b1b98c10a15f87decde094d
 SHA512:
-  metadata.gz: 88068b7c0075fb5a23ceb713459f14ecdf8bddb3300f112bf0dd85a7c3a917f5d7607b1127709747af9ffd7737a038d4392498b43f19c759cebca535c653cdb9
-  data.tar.gz: da5ea3b6205ed36515493143e98d1188fe54f708e3135ec87845b44b8f7cd1b22fb24deb392bfd84f6f97f0a7261f5582647b09d81ef3c7525d11b9c9cc221a6
+  metadata.gz: 8000cf349d155abaf9feec697a440e3a9d1db4112cb2257005900b712774a6d05b5c41f5f68f8ca2a05443385e202b62ea5ffa021c92a47e6038ad7b65213107
+  data.tar.gz: 7adf72224a086374d1b54034d6f3ada3fb05537acc3d031dfdaf701658dd5cc05121f232f4be80075070db54750f48ad714d18e0b2fd9f0ff2d8aab7bae77bd2

data/lib/dynamic-active-model/associations.rb

@@ -1,26 +1,61 @@
 # frozen_string_literal: true
 
 module DynamicActiveModel
-  # DynamicActiveModel::Associations iterates over the models of a
-  #  database and adds has_many and belongs_to based on foreign keys
+  # The Associations class is responsible for automatically detecting and setting up
+  # ActiveRecord relationships between models based on database schema analysis.
+  # It supports the following relationship types:
+  # - belongs_to
+  # - has_many
+  # - has_one (automatically detected from unique constraints)
+  # - has_and_belongs_to_many (automatically detected from join tables)
+  #
+  # @example Basic Usage
+  #   db = DynamicActiveModel::Database.new(DB, database_config)
+  #   db.create_models!
+  #   associations = DynamicActiveModel::Associations.new(db)
+  #   associations.build!
+  #
+  # @example Custom Foreign Key
+  #   associations.add_foreign_key('users', 'manager_id', 'manager')
   class Associations
-    attr_reader :database,
-                :table_indexes
-
+    # @return [Database] The database instance containing the models
+    attr_reader :database
+    
+    # @return [Hash] Mapping of table names to their indexes
+    attr_reader :table_indexes
+    
+    # @return [Array] List of detected join tables
+    attr_reader :join_tables
+
+    # Initializes a new Associations instance
+    # @param database [Database] The database instance containing the models
     def initialize(database)
       @database = database
       @table_indexes = {}
-      @foreign_keys = database.models.each_with_object({}) do |model, hsh|
-        hsh[model.table_name] = ForeignKey.new(model)
+      @join_tables = []
+      @foreign_keys = {}
+      database.models.each do |model|
+        @foreign_keys[model.table_name] = ForeignKey.new(model)
         @table_indexes[model.table_name] = model.connection.indexes(model.table_name)
+        @join_tables << model if join_table?(model)
       end
     end
 
+    # Adds a custom foreign key relationship
+    # @param table_name [String] Name of the table with the foreign key
+    # @param foreign_key [String] Name of the foreign key column
+    # @param relationship_name [String, nil] Custom name for the relationship
     def add_foreign_key(table_name, foreign_key, relationship_name = nil)
       @foreign_keys[table_name].add(foreign_key, relationship_name)
     end
 
-    # iterates over the models and adds relationships
+    # Builds all relationships between models based on foreign keys and constraints
+    # This method:
+    # 1. Maps foreign keys to their corresponding models
+    # 2. Adds belongs_to relationships
+    # 3. Adds has_many or has_one relationships based on unique constraints
+    # 4. Sets up has_and_belongs_to_many relationships for join tables
+    # @return [void]
     def build!
       foreign_key_to_models = create_foreign_key_to_model_map
 
@@ -35,10 +70,31 @@ module DynamicActiveModel
           end
         end
       end
+
+      @join_tables.each do |join_table_model|
+        models = join_table_model.column_names.map { |column_name| foreign_key_to_models[column_name.downcase]&.first&.first }.compact
+        if models.size == 2
+          add_has_and_belongs_to_many(join_table_model, models)
+        end
+      end
     end
 
     private
 
+    # Adds has_and_belongs_to_many relationships between two models
+    # @param join_table_model [Class] The join table model
+    # @param models [Array<Class>] The two models to be related
+    def add_has_and_belongs_to_many(join_table_model, models)
+      model1, model2 = *models
+      model1.has_and_belongs_to_many model2.table_name.pluralize.to_sym, join_table: join_table_model.table_name, class_name: model2.name
+      model2.has_and_belongs_to_many model1.table_name.pluralize.to_sym, join_table: join_table_model.table_name, class_name: model1.name
+    end
+
+    # Adds appropriate relationships between two models
+    # @param relationship_name [String] Name of the relationship
+    # @param model [Class] The model with the foreign key
+    # @param belongs_to_model [Class] The model being referenced
+    # @param foreign_key [String] The foreign key column name
     def add_relationships(relationship_name, model, belongs_to_model, foreign_key)
       add_belongs_to(relationship_name, model, belongs_to_model, foreign_key)
       if unique_index?(model, foreign_key)
@@ -48,6 +104,11 @@ module DynamicActiveModel
       end
     end
 
+    # Adds a belongs_to relationship to a model
+    # @param relationship_name [String] Name of the relationship
+    # @param model [Class] The model with the foreign key
+    # @param belongs_to_model [Class] The model being referenced
+    # @param foreign_key [String] The foreign key column name
     def add_belongs_to(relationship_name, model, belongs_to_model, foreign_key)
       model.belongs_to(
         relationship_name.singularize.to_sym,
@@ -57,6 +118,11 @@ module DynamicActiveModel
       )
     end
 
+    # Adds a has_many relationship to a model
+    # @param relationship_name [String] Name of the relationship
+    # @param model [Class] The model with the foreign key
+    # @param has_many_model [Class] The model being referenced
+    # @param foreign_key [String] The foreign key column name
     def add_has_many(relationship_name, model, has_many_model, foreign_key)
       model.has_many(
         generate_has_many_association_name(relationship_name, model, has_many_model),
@@ -66,6 +132,11 @@ module DynamicActiveModel
       )
     end
 
+    # Adds a has_one relationship to a model
+    # @param relationship_name [String] Name of the relationship
+    # @param model [Class] The model with the foreign key
+    # @param has_one_model [Class] The model being referenced
+    # @param foreign_key [String] The foreign key column name
     def add_has_one(relationship_name, model, has_one_model, foreign_key)
       model.has_one(
         generate_has_one_association_name(relationship_name, model, has_one_model),
@@ -75,6 +146,8 @@ module DynamicActiveModel
       )
     end
 
+    # Creates a mapping of foreign key column names to their corresponding models
+    # @return [Hash] Mapping of foreign key names to model and relationship name pairs
     def create_foreign_key_to_model_map
       @foreign_keys.values.each_with_object({}) do |foreign_key, hsh|
         foreign_key.keys.each do |key, relationship_name|
@@ -84,16 +157,26 @@ module DynamicActiveModel
       end
     end
 
+    # Generates an appropriate name for a has_many association
+    # @param relationship_name [String] Original relationship name
+    # @param model [Class] The model with the foreign key
+    # @param has_many_model [Class] The model being referenced
+    # @return [Symbol] The generated association name
     def generate_has_many_association_name(relationship_name, model, has_many_model)
       name =
         if relationship_name == model.table_name.underscore
           has_many_model.table_name
         else
-          relationship_name
+          "#{relationship_name}_#{has_many_model.table_name}"
         end
       name.underscore.pluralize.to_sym
     end
 
+    # Generates an appropriate name for a has_one association
+    # @param relationship_name [String] Original relationship name
+    # @param model [Class] The model with the foreign key
+    # @param has_one_model [Class] The model being referenced
+    # @return [Symbol] The generated association name
     def generate_has_one_association_name(relationship_name, model, has_one_model)
       name =
         if relationship_name == model.table_name.underscore
@@ -104,6 +187,10 @@ module DynamicActiveModel
       name.underscore.singularize.to_sym
     end
 
+    # Checks if a foreign key column has a unique index
+    # @param model [Class] The model to check
+    # @param foreign_key [String] The foreign key column name
+    # @return [Boolean] Whether the foreign key has a unique index
     def unique_index?(model, foreign_key)
       indexes = table_indexes[model.table_name]
       indexes.any? do |index|
@@ -112,5 +199,14 @@ module DynamicActiveModel
           index.columns.first == foreign_key
       end
     end
+
+    # Detects if a model represents a join table for has_and_belongs_to_many
+    # @param model [Class] The model to check
+    # @return [Boolean] Whether the model is a join table
+    def join_table?(model)
+      model.primary_key.nil? &&
+        model.columns.size == 2 &&
+        model.columns.all? { |column| column.name =~ /#{ForeignKey.id_suffix}$/ }
+    end
   end
 end

data/lib/dynamic-active-model/dangerous_attributes_patch.rb

@@ -1,9 +1,29 @@
 # frozen_string_literal: true
 
 module DynamicActiveModel
-  # DynamicActiveModel::DangerousAttributesPatch is used to remove dangerous attribute names
-  # from attribute_names method in ActiveRecord
+  # The DangerousAttributesPatch module is a safety feature that prevents conflicts
+  # between database column names and Ruby reserved words or ActiveRecord methods.
+  # It automatically detects and ignores columns that could cause conflicts,
+  # particularly focusing on boolean columns that might conflict with Ruby's
+  # question mark methods.
+  #
+  # @example Basic Usage
+  #   class User < ActiveRecord::Base
+  #     include DynamicActiveModel::DangerousAttributesPatch
+  #   end
+  #
+  # @example With Boolean Column
+  #   # If a table has a boolean column named 'class',
+  #   # it will be automatically ignored to prevent conflicts
+  #   # with Ruby's Object#class method
   module DangerousAttributesPatch
+    # Extends the including class with dangerous attribute protection
+    # This method:
+    # 1. Checks if the class has any attributes
+    # 2. Identifies columns that could cause conflicts
+    # 3. Adds those columns to the ignored_columns list
+    #
+    # @param base [Class] The ActiveRecord model class
     def self.included(base)
       return unless base.attribute_names
 

data/lib/dynamic-active-model/database.rb

@@ -1,19 +1,50 @@
 # frozen_string_literal: true
 
 module DynamicActiveModel
-  # DynamicActiveModel::Database iterates over the tables of a
-  #  database and create ActiveRecord models
+  # The Database class is responsible for connecting to a database and creating
+  # ActiveRecord models from its tables. It provides functionality for:
+  # - Table filtering (blacklist/whitelist)
+  # - Model creation and management
+  # - Model updates and extensions
+  #
+  # @example Basic Usage
+  #   db = DynamicActiveModel::Database.new(DB, database_config)
+  #   db.create_models!
+  #
+  # @example Table Filtering
+  #   db.skip_table 'temporary_data'
+  #   db.include_table 'users'
+  #   db.create_models!
+  #
+  # @example Model Updates
+  #   db.update_model(:users) do
+  #     def full_name
+  #       "#{first_name} #{last_name}"
+  #     end
+  #   end
   class Database
-    attr_reader :table_class_names,
-                :factory,
-                :models
-
+    # @return [Hash] Mapping of table names to custom class names
+    attr_reader :table_class_names
+    
+    # @return [Factory] Factory instance used for model creation
+    attr_reader :factory
+    
+    # @return [Array] List of created model classes
+    attr_reader :models
+
+    # Helper class for updating model definitions
     ModelUpdater = Struct.new(:model) do
+      # Updates a model's definition with the provided block
+      # @param block [Proc] Code to evaluate in the model's context
       def update_model(&block)
         model.class_eval(&block)
       end
     end
 
+    # Initializes a new Database instance
+    # @param base_module [Module] The namespace for created models
+    # @param connection_options [Hash] Database connection options
+    # @param base_class_name [String, nil] Optional base class name for models
     def initialize(base_module, connection_options, base_class_name = nil)
       @factory = Factory.new(base_module, connection_options, base_class_name)
       @table_class_names = {}
@@ -24,6 +55,8 @@ module DynamicActiveModel
       @models = []
     end
 
+    # Adds a table to the blacklist
+    # @param table [String, Regexp] Table name or pattern to skip
     def skip_table(table)
       if table.is_a?(Regexp)
         @skip_table_matchers << table
@@ -32,10 +65,14 @@ module DynamicActiveModel
       end
     end
 
+    # Adds multiple tables to the blacklist
+    # @param tables [Array<String, Regexp>] Table names or patterns to skip
     def skip_tables(tables)
       tables.each { |table| skip_table(table) }
     end
 
+    # Adds a table to the whitelist
+    # @param table [String, Regexp] Table name or pattern to include
     def include_table(table)
       if table.is_a?(Regexp)
         @include_table_matchers << table
@@ -44,14 +81,21 @@ module DynamicActiveModel
       end
     end
 
+    # Adds multiple tables to the whitelist
+    # @param tables [Array<String, Regexp>] Table names or patterns to include
     def include_tables(tables)
       tables.each { |table| include_table(table) }
     end
 
+    # Sets a custom class name for a table
+    # @param table_name [String] Name of the table
+    # @param class_name [String] Custom class name to use
     def table_class_name(table_name, class_name)
       @table_class_names[table_name.to_s] = class_name
     end
 
+    # Creates ActiveRecord models for all included tables
+    # @return [Array] List of created model classes
     def create_models!
       @factory.base_class.connection.tables.each do |table_name|
         next if skip_table?(table_name)
@@ -61,14 +105,18 @@ module DynamicActiveModel
       end
     end
 
+    # @return [Array] List of all skipped tables and patterns
     def skipped_tables
       @skip_tables + @skip_table_matchers
     end
 
+    # @return [Array] List of all included tables and patterns
     def included_tables
       @include_tables + @include_table_matchers
     end
 
+    # Disables Single Table Inheritance (STI) for all models
+    # @return [void]
     def disable_standard_table_inheritance!
       models.each do |model|
         model.inheritance_column = :_type_disabled if model.attribute_names.include?('type')
@@ -76,11 +124,18 @@ module DynamicActiveModel
     end
     alias disable_sti! disable_standard_table_inheritance!
 
+    # Finds a model by table name
+    # @param table_name [String] Name of the table
+    # @return [Class, nil] The model class or nil if not found
     def get_model(table_name)
       table_name = table_name.to_s
       models.detect { |model| model.table_name == table_name }
     end
 
+    # Finds a model by table name, raising an error if not found
+    # @param table_name [String] Name of the table
+    # @return [Class] The model class
+    # @raise [ModelNotFound] If no model is found for the table
     def get_model!(table_name)
       model = get_model(table_name)
       return model if model
@@ -88,6 +143,11 @@ module DynamicActiveModel
       raise ::DynamicActiveModel::ModelNotFound, "no model found for table #{table_name}"
     end
 
+    # Updates a model's definition
+    # @param table_name [String] Name of the table
+    # @param file [String, nil] Path to a file containing model updates
+    # @param block [Proc] Code to evaluate in the model's context
+    # @return [Class] The updated model class
     def update_model(table_name, file = nil, &block)
       model = get_model!(table_name)
       ModelUpdater.new(model).instance_eval(File.read(file)) if file
@@ -95,6 +155,10 @@ module DynamicActiveModel
       model
     end
 
+    # Updates all models using extension files from a directory
+    # @param base_dir [String] Directory containing extension files
+    # @param ext [String] Extension for model update files
+    # @return [void]
     def update_all_models(base_dir, ext = '.ext.rb')
       Dir.glob("#{base_dir}/*#{ext}") do |file|
         next unless File.file?(file)
@@ -106,11 +170,17 @@ module DynamicActiveModel
 
     private
 
+    # Checks if a table should be skipped
+    # @param table_name [String] Name of the table
+    # @return [Boolean] Whether the table should be skipped
     def skip_table?(table_name)
       @skip_tables.include?(table_name.to_s) ||
         @skip_table_matchers.any? { |r| r.match(table_name) }
     end
 
+    # Checks if a table should be included
+    # @param table_name [String] Name of the table
+    # @return [Boolean] Whether the table should be included
     def include_table?(table_name)
       (@include_tables.empty? && @include_table_matchers.empty?) ||
         @include_tables.include?(table_name) ||

data/lib/dynamic-active-model/explorer.rb

@@ -1,14 +1,45 @@
 # frozen_string_literal: true
 
 module DynamicActiveModel
-  # DynamicActiveModel::Explorer creates models and relationships
+  # The Explorer module provides a high-level interface for automatically discovering
+  # and setting up ActiveRecord models and their relationships from a database schema.
+  # It combines the functionality of Database and Associations classes into a simple
+  # one-call interface.
+  #
+  # @example Basic Usage
+  #   module DB; end
+  #   DynamicActiveModel::Explorer.explore(DB, database_config)
+  #
+  # @example With Table Filtering
+  #   skip_tables = ['temporary_data', 'audit_logs']
+  #   DynamicActiveModel::Explorer.explore(DB, database_config, skip_tables)
+  #
+  # @example With Custom Relationships
+  #   relationships = {
+  #     'users' => {
+  #       'manager_id' => 'manager',
+  #       'department_id' => 'department'
+  #     }
+  #   }
+  #   DynamicActiveModel::Explorer.explore(DB, database_config, [], relationships)
   module Explorer
+    # Creates models and sets up relationships in a single call
+    # @param base_module [Module] The namespace for created models
+    # @param connection_options [Hash] Database connection options
+    # @param skip_tables [Array<String, Regexp>] Tables to exclude from model creation
+    # @param relationships [Hash] Custom foreign key relationships to add
+    # @return [Database] The configured database instance
     def self.explore(base_module, connection_options, skip_tables = [], relationships = {})
       database = create_models!(base_module, connection_options, skip_tables)
       build_relationships!(database, relationships)
       database
     end
 
+    # Creates ActiveRecord models from database tables
+    # @param base_module [Module] The namespace for created models
+    # @param connection_options [Hash] Database connection options
+    # @param skip_tables [Array<String, Regexp>] Tables to exclude from model creation
+    # @return [Database] The configured database instance
     def self.create_models!(base_module, connection_options, skip_tables)
       database = Database.new(base_module, connection_options)
       skip_tables.each do |table_name|
@@ -19,6 +50,10 @@ module DynamicActiveModel
       database
     end
 
+    # Sets up relationships between created models
+    # @param database [Database] The database instance containing the models
+    # @param relationships [Hash] Custom foreign key relationships to add
+    # @return [void]
     def self.build_relationships!(database, relationships)
       relations = Associations.new(database)
       relationships.each do |table_name, foreign_keys|

data/lib/dynamic-active-model/factory.rb

@@ -1,22 +1,48 @@
 # frozen_string_literal: true
 
 module DynamicActiveModel
-  # DynamicActiveModel::Factory creates ActiveRecord class for tables
+  # The Factory class is responsible for creating ActiveRecord model classes
+  # from database tables. It handles:
+  # - Base class creation and connection setup
+  # - Model class generation with proper naming
+  # - Table name assignment
+  # - Safety patches for dangerous attributes
+  #
+  # @example Basic Usage
+  #   factory = DynamicActiveModel::Factory.new(DB, database_config)
+  #   model = factory.create('users')
+  #
+  # @example With Custom Class Name
+  #   factory = DynamicActiveModel::Factory.new(DB, database_config)
+  #   model = factory.create('users', 'CustomUser')
   class Factory
+    # @return [Class] The base class for all generated models
     attr_writer :base_class
 
+    # Initializes a new Factory instance
+    # @param base_module [Module] The namespace for created models
+    # @param connection_options [Hash] Database connection options
+    # @param base_class_name [Symbol, nil] Optional name for the base class
     def initialize(base_module, connection_options, base_class_name = nil)
       @base_module = base_module
       @connection_options = connection_options
       @base_class_name = base_class_name || :DynamicAbstractBase
     end
 
+    # Creates a new model class for a table if it doesn't exist
+    # @param table_name [String] Name of the database table
+    # @param class_name [String, nil] Optional custom class name
+    # @return [Class] The model class
     def create(table_name, class_name = nil)
       class_name ||= generate_class_name(table_name)
       create!(table_name, class_name) unless @base_module.const_defined?(class_name)
       @base_module.const_get(class_name)
     end
 
+    # Creates a new model class for a table, overwriting if it exists
+    # @param table_name [String] Name of the database table
+    # @param class_name [String] Name for the model class
+    # @return [Class] The model class
     def create!(table_name, class_name)
       kls = Class.new(base_class) do
         self.table_name = table_name
@@ -26,7 +52,12 @@ module DynamicActiveModel
       @base_module.const_get(class_name)
     end
 
-    # rubocop:disable Metrics/MethodLength
+    # Gets or creates the base class for all models
+    # This method:
+    # 1. Creates an abstract ActiveRecord::Base subclass if needed
+    # 2. Establishes the database connection
+    # 3. Returns the configured base class
+    # @return [Class] The base class for all models
     def base_class
       @base_class ||=
         begin
@@ -44,8 +75,10 @@ module DynamicActiveModel
           end
         end
     end
-    # rubocop:enable Metrics/MethodLength
 
+    # Generates a valid Ruby class name from a table name
+    # @param table_name [String] Name of the database table
+    # @return [String] A valid Ruby class name
     def generate_class_name(table_name)
       class_name = table_name.classify
       return "N#{class_name}" if class_name =~ /\A\d/

data/lib/dynamic-active-model/foreign_key.rb

@@ -1,33 +1,60 @@
 # frozen_string_literal: true
 
 module DynamicActiveModel
-  # DynamicActiveModel::ForeignKey tracks foreign keys related to the model
+  # The ForeignKey class manages foreign key relationships for a model.
+  # It provides functionality for:
+  # - Tracking foreign key columns
+  # - Generating standard foreign key names
+  # - Managing custom relationship names
+  # - Configuring the foreign key suffix
+  #
+  # @example Basic Usage
+  #   model = DB::User
+  #   fk = DynamicActiveModel::ForeignKey.new(model)
+  #   fk.add('manager_id', 'manager')
+  #
+  # @example Custom Suffix
+  #   DynamicActiveModel::ForeignKey.id_suffix = '_ref'
   class ForeignKey
-    attr_reader :model,
-                :keys
+    # @return [Class] The model this foreign key belongs to
+    attr_reader :model
+    
+    # @return [Hash] Mapping of foreign key columns to relationship names
+    attr_reader :keys
 
+    # Default suffix used for foreign key columns
     DEFAULT_ID_SUFFIX = '_id'
 
+    # Gets the current foreign key suffix
+    # @return [String] The suffix used for foreign key columns
     def self.id_suffix
       @id_suffix || DEFAULT_ID_SUFFIX
     end
 
-    # rubocop:disable Style/TrivialAccessors
+    # Sets a custom foreign key suffix
+    # @param val [String] The new suffix to use
     def self.id_suffix=(val)
       @id_suffix = val
     end
-    # rubocop:enable Style/TrivialAccessors
 
+    # Initializes a new ForeignKey instance
+    # @param model [Class] The model to track foreign keys for
     def initialize(model)
       @model = model
       @keys = {}
       add(generate_foreign_key(model.table_name))
     end
 
+    # Adds a foreign key to track
+    # @param key [String] The foreign key column name
+    # @param relationship_name [String, nil] Optional custom name for the relationship
     def add(key, relationship_name = nil)
       @keys[key] = relationship_name || model.table_name.underscore
     end
 
+    # Generates a standard foreign key name from a table name
+    # @param table_name [String] The name of the referenced table
+    # @return [String] The generated foreign key column name
     def generate_foreign_key(table_name)
       table_name.underscore.singularize + self.class.id_suffix
     end

data/lib/dynamic-active-model/setup.rb

@@ -3,19 +3,45 @@
 require 'inheritance-helper'
 
 module DynamicActiveModel
-  # DynamicActiveModel::Explorer creates models and relationships
+  # The Setup module provides configuration and initialization methods for
+  # DynamicActiveModel. It allows you to:
+  # - Configure database connections
+  # - Specify tables to skip
+  # - Define custom relationships
+  # - Set up model extensions
+  #
+  # @example Basic Usage
+  #   module DB
+  #     include DynamicActiveModel::Setup
+  #     connection_options database_config
+  #     skip_tables ['temporary_data']
+  #     create_models!
+  #   end
+  #
+  # @example With Custom Relationships
+  #   module DB
+  #     include DynamicActiveModel::Setup
+  #     foreign_key 'users', 'manager_id', 'manager'
+  #     create_models!
+  #   end
   module Setup
+    # Extends the including module with configuration methods
+    # @param base [Module] The module including this module
     def self.included(base)
       base.extend InheritanceHelper::Methods
       base.extend ClassMethods
     end
 
-    # ClassMethods various class methods for configuring a module
+    # ClassMethods provides various class methods for configuring a module
     module ClassMethods
+      # Gets the database instance
+      # @return [Database, nil] The configured database instance
       def database
         nil
       end
 
+      # Gets the current configuration
+      # @return [Hash] The configuration hash with default values
       def dynamic_active_model_config
         {
           connection_options: nil,
@@ -26,6 +52,9 @@ module DynamicActiveModel
         }
       end
 
+      # Sets or gets the database connection options
+      # @param options [Hash, String, nil] Database configuration or named configuration
+      # @return [Hash] The current connection options
       def connection_options(options = nil)
         if options.is_a?(String)
           name = options
@@ -47,6 +76,9 @@ module DynamicActiveModel
         dynamic_active_model_config[:connection_options]
       end
 
+      # Sets or gets the list of tables to skip
+      # @param tables [Array<String>, nil] Tables to skip
+      # @return [Array<String>] The current list of skipped tables
       def skip_tables(tables = nil)
         if tables
           config = dynamic_active_model_config
@@ -56,12 +88,17 @@ module DynamicActiveModel
         dynamic_active_model_config[:skip_tables]
       end
 
+      # Adds a single table to the skip list
+      # @param table [String] Table to skip
       def skip_table(table)
         config = dynamic_active_model_config
         config[:skip_tables] << table
         redefine_class_method(:dynamic_active_model_config, config)
       end
 
+      # Sets or gets the custom relationships
+      # @param all_relationships [Hash, nil] All custom relationships
+      # @return [Hash] The current relationships
       def relationships(all_relationships = nil)
         if all_relationships
           config = dynamic_active_model_config
@@ -71,6 +108,10 @@ module DynamicActiveModel
         dynamic_active_model_config[:relationships]
       end
 
+      # Adds a custom foreign key relationship
+      # @param table_name [String] Name of the table
+      # @param foreign_key [String] Name of the foreign key column
+      # @param relationship_name [String] Name for the relationship
       def foreign_key(table_name, foreign_key, relationship_name)
         config = dynamic_active_model_config
         current_relationships = config[:relationships]
@@ -79,6 +120,9 @@ module DynamicActiveModel
         redefine_class_method(:dynamic_active_model_config, config)
       end
 
+      # Sets or gets the path for model extensions
+      # @param path [String, nil] Path to extension files
+      # @return [String, nil] The current extensions path
       def extensions_path(path = nil)
         if path
           config = dynamic_active_model_config
@@ -88,6 +132,9 @@ module DynamicActiveModel
         dynamic_active_model_config[:extensions_path]
       end
 
+      # Sets or gets the suffix for extension files
+      # @param suffix [String, nil] File extension suffix
+      # @return [String] The current extensions suffix
       def extensions_suffix(suffix = nil)
         if suffix
           config = dynamic_active_model_config
@@ -97,6 +144,11 @@ module DynamicActiveModel
         dynamic_active_model_config[:extensions_suffix]
       end
 
+      # Creates all models and applies extensions
+      # This method:
+      # 1. Creates models using Explorer
+      # 2. Applies any model extensions if configured
+      # @return [Database] The configured database instance
       def create_models!
         redefine_class_method(
           :database,

data/lib/dynamic-active-model/template_class_file.rb

@@ -1,17 +1,41 @@
 # frozen_string_literal: true
 
 module DynamicActiveModel
-  # DynamicActiveModel::TemplateClassFile creates ActiveRecord file for model
+  # The TemplateClassFile class generates Ruby source files for ActiveRecord models.
+  # It creates properly formatted class definitions that include:
+  # - Table name configuration
+  # - Has many relationships
+  # - Belongs to relationships
+  # - Has one relationships
+  # - Has and belongs to many relationships
+  # - Custom association options
+  #
+  # @example Basic Usage
+  #   model = DB::User
+  #   template = DynamicActiveModel::TemplateClassFile.new(model)
+  #   template.create_template!('app/models')
+  #
+  # @example Generate Source String
+  #   model = DB::User
+  #   template = DynamicActiveModel::TemplateClassFile.new(model)
+  #   source = template.to_s
   class TemplateClassFile
+    # Initializes a new TemplateClassFile instance
+    # @param model [Class] The ActiveRecord model to generate a template for
     def initialize(model)
       @model = model
     end
 
+    # Creates a Ruby source file for the model
+    # @param dir [String] Directory to create the file in
+    # @return [void]
     def create_template!(dir)
       file = dir + '/' + @model.name.underscore + '.rb'
       File.open(file, 'wb') { |f| f.write(to_s) }
     end
 
+    # Generates the Ruby source code for the model
+    # @return [String] The complete model class definition
     def to_s
       str = "class #{@model.name} < ActiveRecord::Base\n".dup
       str << "  self.table_name = #{@model.table_name.to_sym.inspect}\n" unless @model.name.underscore.pluralize == @model.table_name
@@ -21,27 +45,76 @@ module DynamicActiveModel
       all_belongs_to_relationships.each do |assoc|
         append_association!(str, assoc)
       end
+      all_has_one_relationships.each do |assoc|
+        append_association!(str, assoc)
+      end
+      all_has_and_belongs_to_many_relationships.each do |assoc|
+        append_association!(str, assoc)
+      end
       str << "end\n"
       str
     end
 
     private
 
+    # Gets all has_many relationships for the model
+    # @return [Array<ActiveRecord::Reflection::HasManyReflection>]
     def all_has_many_relationships
       @model.reflect_on_all_associations.select do |assoc|
         assoc.is_a?(ActiveRecord::Reflection::HasManyReflection)
       end
     end
 
+    # Gets all belongs_to relationships for the model
+    # @return [Array<ActiveRecord::Reflection::BelongsToReflection>]
     def all_belongs_to_relationships
       @model.reflect_on_all_associations.select do |assoc|
         assoc.is_a?(ActiveRecord::Reflection::BelongsToReflection)
       end
     end
 
+    # Gets all has_one relationships for the model
+    # @return [Array<ActiveRecord::Reflection::HasOneReflection>]
+    def all_has_one_relationships
+      @model.reflect_on_all_associations.select do |assoc|
+        assoc.is_a?(ActiveRecord::Reflection::HasOneReflection)
+      end
+    end
+
+    # Gets all has_and_belongs_to_many relationships for the model
+    # @return [Array<ActiveRecord::Reflection::HasAndBelongsToManyReflection>]
+    def all_has_and_belongs_to_many_relationships
+      @model.reflect_on_all_associations.select do |assoc|
+        assoc.is_a?(ActiveRecord::Reflection::HasAndBelongsToManyReflection)
+      end
+    end
+
+    # Appends an association definition to the source string
+    # @param str [String] The source string being built
+    # @param assoc [ActiveRecord::Reflection::AssociationReflection] The association to add
     def append_association!(str, assoc)
-      assoc_type = assoc.is_a?(ActiveRecord::Reflection::HasManyReflection) ? 'has_many' : 'belongs_to'
-      association_options = assoc_type == 'has_many' ? has_many_association_options(assoc) : belongs_to_association_options(assoc)
+      assoc_type = case assoc
+                   when ActiveRecord::Reflection::HasManyReflection
+                     'has_many'
+                   when ActiveRecord::Reflection::BelongsToReflection
+                     'belongs_to'
+                   when ActiveRecord::Reflection::HasOneReflection
+                     'has_one'
+                   when ActiveRecord::Reflection::HasAndBelongsToManyReflection
+                     'has_and_belongs_to_many'
+                   end
+
+      association_options = case assoc_type
+                           when 'has_many'
+                             has_many_association_options(assoc)
+                           when 'belongs_to'
+                             belongs_to_association_options(assoc)
+                           when 'has_one'
+                             has_one_association_options(assoc)
+                           when 'has_and_belongs_to_many'
+                             has_and_belongs_to_many_association_options(assoc)
+                           end
+
       str << "  #{assoc_type} #{assoc.name.inspect}"
       unless association_options.empty?
         association_options.each do |name, value|
@@ -51,6 +124,9 @@ module DynamicActiveModel
       str << "\n"
     end
 
+    # Gets the options for a has_many association
+    # @param assoc [ActiveRecord::Reflection::HasManyReflection] The association
+    # @return [Hash] The association options
     def has_many_association_options(assoc)
       options = {}
       options[:class_name] = assoc.options[:class_name] unless assoc.options[:class_name].underscore.pluralize == assoc.name.to_s
@@ -59,6 +135,9 @@ module DynamicActiveModel
       options
     end
 
+    # Gets the options for a belongs_to association
+    # @param assoc [ActiveRecord::Reflection::BelongsToReflection] The association
+    # @return [Hash] The association options
     def belongs_to_association_options(assoc)
       options = {}
       options[:class_name] = assoc.options[:class_name] unless assoc.options[:class_name] == assoc.name.to_s.classify
@@ -67,10 +146,43 @@ module DynamicActiveModel
       options
     end
 
+    # Gets the options for a has_one association
+    # @param assoc [ActiveRecord::Reflection::HasOneReflection] The association
+    # @return [Hash] The association options
+    def has_one_association_options(assoc)
+      options = {}
+      options[:class_name] = assoc.options[:class_name] unless assoc.options[:class_name].underscore.singularize == assoc.name.to_s
+      options[:foreign_key] = assoc.options[:foreign_key] unless assoc.options[:foreign_key] == default_foreign_key_name
+      options[:primary_key] = assoc.options[:primary_key] unless assoc.options[:primary_key] == 'id'
+      options
+    end
+
+    # Gets the options for a has_and_belongs_to_many association
+    # @param assoc [ActiveRecord::Reflection::HasAndBelongsToManyReflection] The association
+    # @return [Hash] The association options
+    def has_and_belongs_to_many_association_options(assoc)
+      options = {}
+      options[:join_table] = assoc.options[:join_table] if assoc.options[:join_table]
+      options[:class_name] = assoc.options[:class_name] unless assoc.options[:class_name].underscore.singularize == assoc.name.to_s
+      options
+    end
+
+    # Gets the default foreign key name for the model
+    # @return [String] The default foreign key name
     def default_foreign_key_name
       @model.table_name.underscore.singularize + '_id'
     end
 
+    # Generates the default foreign key for the associated model
+    # @param assoc [ActiveRecord::Reflection::HasAndBelongsToManyReflection] The association
+    # @return [String] The generated foreign key name
+    def generate_association_foreign_key(assoc)
+      assoc.options[:class_name].underscore.singularize + '_id'
+    end
+
+    # Gets a constant by its fully qualified name
+    # @param class_name [String] The fully qualified class name
+    # @return [Class] The resolved class
     def const_get(class_name)
       class_name.split('::').inject(Object) { |mod, name| mod.const_get(name) }
     end

data/lib/dynamic-active-model.rb

@@ -1,15 +1,49 @@
 # frozen_string_literal: true
 
-# DynamicActiveModel module for create ActiveRecord models
+# DynamicActiveModel is a Ruby gem that provides automatic database discovery,
+# model creation, and relationship mapping for Rails applications.
+#
+# It allows developers to dynamically create ActiveRecord models from existing
+# database schemas without manually writing model classes. The gem automatically
+# detects and sets up relationships including has_many, belongs_to, has_one,
+# and has_and_belongs_to_many based on database constraints.
+#
+# @example Basic Usage
+#   module DB; end
+#   DynamicActiveModel::Explorer.explore(DB, database_config)
+#
+# @example Model Extension
+#   db = DynamicActiveModel::Database.new(DB, database_config)
+#   db.update_model(:users) do
+#     def full_name
+#       "#{first_name} #{last_name}"
+#     end
+#   end
 module DynamicActiveModel
+  # Database class handles database connection and model creation
   autoload :Database, 'dynamic-active-model/database'
+  
+  # Safety feature that prevents conflicts with Ruby reserved words
   autoload :DangerousAttributesPatch, 'dynamic-active-model/dangerous_attributes_patch'
+  
+  # High-level interface for model discovery and relationship mapping
   autoload :Explorer, 'dynamic-active-model/explorer'
+  
+  # Manages the creation of model classes
   autoload :Factory, 'dynamic-active-model/factory'
+  
+  # Handles foreign key relationships and constraints
   autoload :ForeignKey, 'dynamic-active-model/foreign_key'
+  
+  # Manages automatic discovery and setup of model relationships
   autoload :Associations, 'dynamic-active-model/associations'
+  
+  # Handles generation of model class files
   autoload :TemplateClassFile, 'dynamic-active-model/template_class_file'
+  
+  # Manages the setup process and configuration
   autoload :Setup, 'dynamic-active-model/setup'
 
+  # Raised when a requested model cannot be found
   class ModelNotFound < StandardError; end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dynamic-active-model
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.4
 platform: ruby
 authors:
 - Doug Youch
 bindir: bin
 cert_chain: []
-date: 2025-05-02 00:00:00.000000000 Z
+date: 2025-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord