support_table_data 1.4.0 → 1.5.1

data/lib/support_table_data/documentation/source_file.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module SupportTableData
+  module Documentation
+    class SourceFile
+      attr_reader :klass, :path
+
+      BEGIN_YARD_COMMENT = "# Begin YARD docs for support_table_data"
+      END_YARD_COMMENT = "# End YARD docs for support_table_data"
+      YARD_COMMENT_REGEX = /^(?<indent>[ \t]*)#{BEGIN_YARD_COMMENT}.*^[ \t]*#{END_YARD_COMMENT}$/m
+      CLASS_DEF_REGEX = /^[ \t]*class [a-zA-Z_0-9:]+.*?$/
+      UPDATE_COMMAND_COMMENT = "# To update these docs, run `bundle exec rake support_table_data:yard_docs`"
+
+      # Initialize a new source file representation.
+      #
+      # @param klass [Class] The model class
+      # @param path [Pathname] The path to the source file
+      def initialize(klass, path)
+        @klass = klass
+        @path = path
+        @source = nil
+      end
+
+      # Return the source code of the file.
+      #
+      # @return [String]
+      def source
+        @source ||= @path.read
+      end
+
+      # Return the source code without any generated YARD documentation.
+      #
+      # @return [String]
+      def source_without_yard_docs
+        "#{source.sub(YARD_COMMENT_REGEX, "").rstrip}#{trailing_newline}"
+      end
+
+      # Return the source code with the generated YARD documentation added.
+      # The YARD docs are identified by a begin and end comment block. By default
+      # the generated docs are added to the end of the file by reopening the class
+      # definition. You can move the comment block inside the original class
+      # if desired.
+      #
+      # @return [String]
+      def source_with_yard_docs
+        yard_docs = YardDoc.new(klass).named_instance_yard_docs
+        return source if yard_docs.nil?
+
+        existing_yard_docs = source.match(YARD_COMMENT_REGEX)
+        if existing_yard_docs
+          indent = existing_yard_docs[:indent]
+          has_class_def = existing_yard_docs.to_s.match?(CLASS_DEF_REGEX)
+          yard_docs = yard_docs.lines.map { |line| line.blank? ? "\n" : "#{indent}#{"  " if has_class_def}#{line}" }.join
+
+          updated_source = source[0, existing_yard_docs.begin(0)]
+          updated_source << "#{indent}#{BEGIN_YARD_COMMENT}\n"
+          updated_source << "#{indent}#{UPDATE_COMMAND_COMMENT}\n"
+          updated_source << "#{indent}class #{klass.name}\n" if has_class_def
+          updated_source << yard_docs
+          updated_source << "\n#{indent}end" if has_class_def
+          updated_source << "\n#{indent}#{END_YARD_COMMENT}"
+          updated_source << source[existing_yard_docs.end(0)..-1]
+          updated_source
+        else
+          yard_comments = <<~SOURCE.chomp("\n")
+            #{BEGIN_YARD_COMMENT}
+            #{UPDATE_COMMAND_COMMENT}
+            class #{klass.name}
+            #{yard_docs.lines.map { |line| line.blank? ? "\n" : "  #{line}" }.join}
+            end
+            #{END_YARD_COMMENT}
+          SOURCE
+          "#{source.rstrip}\n\n#{yard_comments}#{trailing_newline}"
+        end
+      end
+
+      # Check if the YARD documentation in the source file is up to date.
+      #
+      # @return [Boolean]
+      def yard_docs_up_to_date?
+        source == source_with_yard_docs
+      end
+
+      # Check if the source file has any YARD documentation added by support_table_data.
+      #
+      # @return [Boolean]
+      def has_yard_docs?
+        source.match?(YARD_COMMENT_REGEX)
+      end
+
+      private
+
+      def trailing_newline
+        source.end_with?("\n") ? "\n" : ""
+      end
+    end
+  end
+end

data/lib/support_table_data/documentation/yard_doc.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module SupportTableData
+  module Documentation
+    class YardDoc
+      # @param klass [Class] The model class to generate documentation for
+      def initialize(klass)
+        @klass = klass
+      end
+
+      # Generate YARD documentation class definition for the model's helper methods.
+      #
+      # @return [String, nil] The YARD documentation class definition, or nil if no named instances
+      def named_instance_yard_docs
+        instance_names = klass.instance_names
+        generate_yard_docs(instance_names)
+      end
+
+      # Generate YARD documentation comment for named instance singleton method.
+      #
+      # @param name [String] The name of the instance method.
+      # @return [String] The YARD comment text
+      def instance_helper_yard_doc(name)
+        <<~YARD.chomp("\n")
+          # Find the named instance +#{name}+ from the database.
+          #
+          # @!method self.#{name}
+          # @return [#{klass.name}]
+          # @raise [ActiveRecord::RecordNotFound] if the record does not exist
+          # @!visibility public
+        YARD
+      end
+
+      # Generate YARD documentation comment for the predicate method for the named instance.
+      #
+      # @param name [String] The name of the instance method.
+      # @return [String] The YARD comment text
+      def predicate_helper_yard_doc(name)
+        <<~YARD.chomp("\n")
+          # Check if this record is the named instance +#{name}+.
+          #
+          # @!method #{name}?
+          # @return [Boolean]
+          # @!visibility public
+        YARD
+      end
+
+      # Generate YARD documentation comment for the attribute method helper for the named instance.
+      #
+      # @param name [String] The name of the instance method.
+      # @return [String] The YARD comment text
+      def attribute_helper_yard_doc(name, attribute_name)
+        <<~YARD.chomp("\n")
+          # Get the #{attribute_name} attribute from the data file
+          # for the named instance +#{name}+.
+          #
+          # @!method self.#{name}_#{attribute_name}
+          # @return [Object]
+          # @!visibility public
+        YARD
+      end
+
+      private
+
+      attr_reader :klass
+
+      def generate_yard_docs(instance_names)
+        return nil if instance_names.empty?
+
+        yard_lines = ["# @!group Named Instances"]
+
+        # Generate docs for each named instance
+        instance_names.sort.each do |name|
+          yard_lines << ""
+          yard_lines << instance_helper_yard_doc(name)
+          yard_lines << ""
+          yard_lines << predicate_helper_yard_doc(name)
+          klass.support_table_attribute_helpers.each do |attribute_name|
+            yard_lines << ""
+            yard_lines << attribute_helper_yard_doc(name, attribute_name)
+          end
+        end
+
+        yard_lines << ""
+        yard_lines << "# @!endgroup"
+
+        yard_lines.join("\n")
+      end
+    end
+  end
+end

data/lib/support_table_data/documentation.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SupportTableData
+  module Documentation
+  end
+end
+
+require_relative "documentation/source_file"
+require_relative "documentation/yard_doc"

data/lib/support_table_data/railtie.rb

@@ -2,8 +2,29 @@
 
 module SupportTableData
   class Railtie < Rails::Railtie
-    rake_tasks do
+    unless config.respond_to?(:support_table) && config.support_table
+      config.support_table = ActiveSupport::OrderedOptions.new
+    end
+
+    config.support_table.data_directory ||= "db/support_tables"
+    config.support_table.auto_sync ||= true
+
+    initializer "support_table_data" do |app|
+      SupportTableData.data_directory ||= app.root.join(app.config.support_table&.data_directory).to_s
+    end
+
+    rake_tasks do |app|
       load File.expand_path("../tasks/support_table_data.rake", __dir__)
+
+      if app.config.support_table.auto_sync
+        ["db:seed", "db:seed:replant", "db:prepare", "db:test:prepare", "db:fixtures:load"].each do |task_name|
+          next unless Rake::Task.task_defined?(task_name)
+
+          Rake::Task[task_name].enhance do
+            Rake::Task["support_table_data:sync"].invoke
+          end
+        end
+      end
     end
   end
 end

data/lib/support_table_data/validation_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SupportTableData
+  # Error class that is raised when validation fails when loading support table data.
+  # It provides more context than the standard ActiveRecord::RecordInvalid to help identify
+  # which record caused the validation failure.
+  class ValidationError < StandardError
+    def initialize(invalid_record)
+      key_attribute = invalid_record.class.support_table_key_attribute
+      key_value = invalid_record[key_attribute]
+      message = "Validation failed for #{invalid_record.class} with #{key_attribute}: #{key_value.inspect} - " \
+                "#{invalid_record.errors.full_messages.join(", ")}"
+      super(message)
+    end
+  end
+end

data/lib/support_table_data.rb

@@ -8,6 +8,8 @@
 module SupportTableData
   extend ActiveSupport::Concern
 
+  @data_directory = nil
+
   included do
     # Internal variables used for memoization.
     @mutex = Mutex.new
@@ -17,9 +19,13 @@ module SupportTableData
     @support_table_instance_keys = nil
     @support_table_dependencies = []
 
-    # Define the attribute used as the key of the hash in the data files.
-    # This should be a value that never changes. By default the key attribute will be the id.
-    class_attribute :support_table_key_attribute, instance_accessor: false
+    # Private class attribute to hold the key attribute name. Use `support_table_key_attribute` instead.
+    # @private
+    class_attribute :_support_table_key_attribute, instance_accessor: false
+    class << self
+      private :_support_table_key_attribute=
+      private :_support_table_key_attribute
+    end
 
     # Define the directory where data files should be loaded from. This value will override the global
     # value set by SupportTableData.data_directory. This is only used if relative paths are passed
@@ -28,6 +34,20 @@ module SupportTableData
   end
 
   class_methods do
+    # Define the attribute used as the key of the hash in the data files.
+    # This should be an attribute with values that never change.
+    # By default the key attribute will be the table's primary key.
+    def support_table_key_attribute=(attribute_name)
+      self._support_table_key_attribute = attribute_name&.to_s
+    end
+
+    # Get the attribute used as the unique to identify records in the data files.
+    #
+    # @return [String] The name of the key attribute.
+    def support_table_key_attribute
+      _support_table_key_attribute || "id"
+    end
+
     # Synchronize the rows in the table with the values defined in the data files added with
     # `add_support_table_data`. Note that rows will not be deleted if they are no longer in
     # the data files.
@@ -36,36 +56,41 @@ module SupportTableData
     def sync_table_data!
       return unless table_exists?
 
-      key_attribute = (support_table_key_attribute || primary_key).to_s
-      canonical_data = support_table_data.each_with_object({}) { |attributes, hash| hash[attributes[key_attribute].to_s] = attributes }
-      records = where(key_attribute => canonical_data.keys)
+      canonical_data = support_table_data.each_with_object({}) do |attributes, hash|
+        hash[attributes[support_table_key_attribute].to_s] = attributes
+      end
+      records = where(support_table_key_attribute => canonical_data.keys)
       changes = []
 
-      ActiveSupport::Notifications.instrument("support_table_data.sync", class: self) do
-        transaction do
-          records.each do |record|
-            key = record[key_attribute].to_s
-            attributes = canonical_data.delete(key)
-            attributes&.each do |name, value|
-              record.send(:"#{name}=", value) if record.respond_to?(:"#{name}=", true)
+      begin
+        ActiveSupport::Notifications.instrument("support_table_data.sync", class: self) do
+          transaction do
+            records.each do |record|
+              key = record[support_table_key_attribute].to_s
+              attributes = canonical_data.delete(key)
+              attributes&.each do |name, value|
+                record.send(:"#{name}=", value) if record.respond_to?(:"#{name}=", true)
+              end
+              if support_table_record_changed?(record)
+                changes << record.changes
+                record.save!
+              end
             end
-            if support_table_record_changed?(record)
+
+            canonical_data.each_value do |attributes|
+              class_name = attributes[inheritance_column]
+              klass = class_name ? sti_class_for(class_name) : self
+              record = klass.new
+              attributes.each do |name, value|
+                record.send(:"#{name}=", value) if record.respond_to?(:"#{name}=", true)
+              end
               changes << record.changes
               record.save!
             end
           end
-
-          canonical_data.each_value do |attributes|
-            class_name = attributes[inheritance_column]
-            klass = class_name ? sti_class_for(class_name) : self
-            record = klass.new
-            attributes.each do |name, value|
-              record.send(:"#{name}=", value) if record.respond_to?(:"#{name}=", true)
-            end
-            changes << record.changes
-            record.save!
-          end
         end
+      rescue ActiveRecord::RecordInvalid => e
+        raise SupportTableData::ValidationError.new(e.record)
       end
 
       changes
@@ -116,14 +141,12 @@ module SupportTableData
     # @return [Array<Hash>] List of attributes for all records in the data files.
     def support_table_data
       data = {}
-      key_attribute = (support_table_key_attribute || primary_key).to_s
-
       @support_table_data_files.each do |data_file_path|
         file_data = support_table_parse_data_file(data_file_path)
         file_data = file_data.values if file_data.is_a?(Hash)
         file_data = Array(file_data).flatten
         file_data.each do |attributes|
-          key_value = attributes[key_attribute].to_s
+          key_value = attributes[support_table_key_attribute].to_s
           existing = data[key_value]
           if existing
             existing.merge!(attributes)
@@ -171,9 +194,8 @@ module SupportTableData
     # @return [ActiveRecord::Base] The instance loaded from the database.
     # @raise [ActiveRecord::RecordNotFound] If the instance does not exist.
     def named_instance(instance_name)
-      key_attribute = (support_table_key_attribute || primary_key).to_s
       instance_name = instance_name.to_s
-      find_by!(key_attribute => @support_table_instance_names[instance_name])
+      find_by!(support_table_key_attribute => @support_table_instance_names[instance_name])
     end
 
     # Get the key values for all instances loaded from the data files.
@@ -181,13 +203,12 @@ module SupportTableData
     # @return [Array] List of all the key attribute values.
     def instance_keys
       if @support_table_instance_keys.nil?
-        key_attribute = (support_table_key_attribute || primary_key).to_s
         values = []
         support_table_data.each do |attributes|
-          key_value = attributes[key_attribute]
+          key_value = attributes[support_table_key_attribute]
           instance = new
-          instance.send(:"#{key_attribute}=", key_value)
-          values << instance.send(key_attribute)
+          instance.send(:"#{support_table_key_attribute}=", key_value)
+          values << instance.send(support_table_key_attribute)
         end
         @support_table_instance_keys = values.uniq
       end
@@ -198,14 +219,12 @@ module SupportTableData
     #
     # @return [Boolean]
     def protected_instance?(instance)
-      key_attribute = (support_table_key_attribute || primary_key).to_s
-
       unless defined?(@protected_keys)
-        keys = support_table_data.collect { |attributes| attributes[key_attribute].to_s }
+        keys = support_table_data.collect { |attributes| attributes[support_table_key_attribute].to_s }
         @protected_keys = keys
       end
 
-      @protected_keys.include?(instance[key_attribute].to_s)
+      @protected_keys.include?(instance[support_table_key_attribute].to_s)
     end
 
     # Explicitly define other support tables that this model depends on. A support table depends
@@ -249,12 +268,11 @@ module SupportTableData
         raise ArgumentError.new("Cannot define named instance #{method_name} on #{name}; name contains illegal characters")
       end
 
-      key_attribute = (support_table_key_attribute || primary_key).to_s
-      key_value = attributes[key_attribute]
+      key_value = attributes[support_table_key_attribute]
 
       unless @support_table_instance_names.include?(method_name)
-        define_support_table_instance_helper(method_name, key_attribute, key_value)
-        define_support_table_predicates_helper("#{method_name}?", key_attribute, key_value)
+        define_support_table_instance_helper(method_name, support_table_key_attribute, key_value)
+        define_support_table_predicates_helper("#{method_name}?", support_table_key_attribute, key_value)
         @support_table_instance_names = @support_table_instance_names.merge(method_name => key_value)
       end
 
@@ -342,19 +360,17 @@ module SupportTableData
   end
 
   class << self
-    # Specify the default directory for data files.
-    attr_writer :data_directory
+    # @attribute [r]
+    #   The the default directory where data files live.
+    #   @return [String, nil]
+    attr_reader :data_directory
 
-    # The directory where data files live by default. If you are running in a Rails environment,
-    # then this will be `db/support_tables`. Otherwise, the current working directory will be used.
+    # Set the default directory where data files live.
     #
-    # @return [String]
-    def data_directory
-      if defined?(@data_directory)
-        @data_directory
-      elsif defined?(Rails.root)
-        Rails.root.join("db", "support_tables").to_s
-      end
+    # @param value [String, Pathname, nil] The path to the directory.
+    # @return [void]
+    def data_directory=(value)
+      @data_directory = value&.to_s
     end
 
     # Sync all support table classes. Classes must already be loaded in order to be synced.
@@ -467,6 +483,8 @@ module SupportTableData
   end
 end
 
+require_relative "support_table_data/validation_error"
+
 if defined?(Rails::Railtie)
   require_relative "support_table_data/railtie"
 end

data/lib/tasks/support_table_data.rake

@@ -3,18 +3,9 @@
 namespace :support_table_data do
   desc "Syncronize data for all models that include SupportTableData."
   task sync: :environment do
-    # Eager load models if we are in a Rails enviroment with eager loading turned off.
-    if defined?(Rails.application)
-      unless Rails.application.config.eager_load
-        if defined?(Rails.application.eager_load!)
-          Rails.application.eager_load!
-        elsif defined?(Rails.autoloaders.zeitwerk_enabled?) && Rails.autoloaders.zeitwerk_enabled?
-          Rails.autoloaders.each(&:eager_load)
-        else
-          warn "Could not eager load models; some support table data may not load"
-        end
-      end
-    end
+    require_relative "utils"
+
+    SupportTableData::Tasks::Utils.eager_load!
 
     logger_callback = lambda do |name, started, finished, unique_id, payload|
       klass = payload[:class]
@@ -31,4 +22,62 @@ namespace :support_table_data do
       SupportTableData.sync_all!
     end
   end
+
+  task yard_docs: "yard_docs:add"
+
+  namespace :yard_docs do
+    desc "Adds YARD documentation comments to models to document the named instance methods. Optional arg: file_path"
+    task :add, [:file_path] => :environment do |_task, args|
+      require_relative "../support_table_data/documentation"
+      require_relative "utils"
+
+      SupportTableData::Tasks::Utils.eager_load!
+      SupportTableData::Tasks::Utils.support_table_sources(args[:file_path]).each do |source_file|
+        next if source_file.yard_docs_up_to_date?
+
+        source_file.path.write(source_file.source_with_yard_docs)
+        puts "Added YARD documentation to #{source_file.klass.name}."
+      end
+    end
+
+    desc "Removes YARD documentation comments added by support_table_data from models. Optional arg: file_path"
+    task :remove, [:file_path] => :environment do |_task, args|
+      require_relative "../support_table_data/documentation"
+      require_relative "utils"
+
+      SupportTableData::Tasks::Utils.eager_load!
+      SupportTableData::Tasks::Utils.support_table_sources(args[:file_path]).each do |source_file|
+        next unless source_file.has_yard_docs?
+
+        source_file.path.write(source_file.source_without_yard_docs)
+        puts "Removed YARD documentation from #{source_file.klass.name}."
+      end
+    end
+
+    desc "Verify that support table models have up to date YARD docs for named instance methods. Optional arg: file_path"
+    task :verify, [:file_path] => :environment do |_task, args|
+      require_relative "../support_table_data/documentation"
+      require_relative "utils"
+
+      SupportTableData::Tasks::Utils.eager_load!
+
+      all_up_to_date = true
+      SupportTableData::Tasks::Utils.support_table_sources(args[:file_path]).each do |source_file|
+        unless source_file.yard_docs_up_to_date?
+          puts "YARD documentation is not up to date for #{source_file.klass.name}."
+          all_up_to_date = false
+        end
+      end
+
+      if all_up_to_date
+        if args[:file_path]
+          puts "YARD documentation is up to date for #{args[:file_path]}."
+        else
+          puts "All support table models have up to date YARD documentation."
+        end
+      else
+        raise "Run bundle exec rake support_table_data:yard_docs to update the documentation."
+      end
+    end
+  end
 end

data/lib/tasks/utils.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module SupportTableData
+  module Tasks
+    module Utils
+      class << self
+        # Helper for eager loading a Rails application.
+        def eager_load!
+          return unless defined?(Rails.application.config.eager_load)
+          return if Rails.application.config.eager_load
+
+          if defined?(Rails.application.eager_load!)
+            Rails.application.eager_load!
+          elsif defined?(Rails.autoloaders.zeitwerk_enabled?) && Rails.autoloaders.zeitwerk_enabled?
+            Rails.autoloaders.each(&:eager_load)
+          else
+            raise "Failed to eager load application."
+          end
+        end
+
+        # Return all source files for models that include SupportTableData.
+        #
+        # @param file_path [String, Pathname, nil] Optional file path to filter by.
+        # @return [Array<SupportTableData::Documentation::SourceFile>]
+        def support_table_sources(file_path = nil)
+          require_relative file_path if file_path
+
+          sources = []
+
+          ActiveRecord::Base.descendants.each do |klass|
+            next unless klass.include?(SupportTableData)
+
+            begin
+              next if klass.instance_names.empty?
+            rescue NoMethodError
+              # Skip models where instance_names is not properly initialized
+              next
+            end
+
+            model_file_path = SupportTableData::Tasks::Utils.model_file_path(klass)
+            next unless model_file_path&.file? && model_file_path.readable?
+
+            sources << Documentation::SourceFile.new(klass, model_file_path)
+          end
+
+          return sources if file_path.nil?
+
+          resolved_path = Pathname.new(file_path.to_s).expand_path
+          sources.select { |source| source.path.expand_path == resolved_path }
+        rescue ArgumentError
+          []
+        end
+
+        def model_file_path(klass)
+          file_path = "#{klass.name.underscore}.rb"
+          model_path = nil
+
+          Rails.application.config.paths["app/models"].each do |path_prefix|
+            path = Pathname.new(path_prefix.to_s).join(file_path)
+            if path&.file? && path.readable?
+              model_path = path
+              break
+            end
+          end
+
+          model_path
+        end
+      end
+    end
+  end
+end

data/support_table_data.gemspec

@@ -12,13 +12,14 @@ Gem::Specification.new do |spec|
   spec.metadata = {
     "homepage_uri" => spec.homepage,
     "source_code_uri" => spec.homepage,
-    "changelog_uri" => "#{spec.homepage}/blob/master/CHANGELOG.md"
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md"
   }
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   ignore_files = %w[
     .
+    AGENTS.md
     Appraisals
     Gemfile
     Gemfile.lock

data/test_app/.gitignore

@@ -0,0 +1,4 @@
+log/*.log
+tmp/
+doc/
+db/*.sqlite3

data/test_app/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+gem "rails", "~> 8.1.1"
+
+gem "sqlite3", "~> 2.9.0"
+
+gem "support_table_data", path: ".."

data/test_app/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative "config/application"
+
+Rails.application.load_tasks

data/test_app/app/models/application_record.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
+end