Add rake task to generate YARD docs

Author: bdurand

.github/workflows/continuous_integration.yml

@@ -28,6 +28,8 @@ jobs:
           - ruby: "ruby"
             standardrb: true
             yard: true
+          - ruby: "4.0"
+            appraisal: "activerecord_8.1"
           - ruby: "3.4"
             appraisal: "activerecord_8.0"
           - ruby: "3.2"

AGENTS.md

@@ -0,0 +1,140 @@
+# Copilot Instructions for support_table_data
+
+## Project Overview
+
+A Ruby gem providing an ActiveRecord mixin for managing support/lookup tables with canonical data defined in YAML/JSON/CSV files. The gem dynamically generates helper methods to reference specific records naturally in code (e.g., `Status.pending` instead of `Status.find_by(name: 'Pending')`).
+
+**Core concept**: Support tables blur the line between data and code—they contain small canonical datasets that must exist for the application to work.
+
+## Architecture
+
+### Key Components
+
+- **`SupportTableData` module** ([lib/support_table_data.rb](lib/support_table_data.rb)): Main concern mixed into ActiveRecord models
+- **Named instance system**: Dynamically generates class methods (`.pending`), predicate methods (`.pending?`), and attribute helpers (`.pending_id`) from hash-based data files
+- **Data sync engine**: Compares canonical data files with database records, creating/updating as needed in atomic transactions
+- **File parsers**: Supports YAML, JSON, and CSV formats with unified interface
+
+### Data Flow
+
+1. Data files (YAML/JSON/CSV) define canonical records with unique key attributes
+2. `add_support_table_data` registers file paths and triggers method generation for hash-based files
+3. `sync_table_data!` parses files, loads matching DB records, and updates/creates within transactions
+4. Named instance methods are dynamically defined via `class_eval` with memoization
+
+## Development Workflows
+
+### Running Tests
+
+```bash
+bundle exec rspec                    # Run all specs
+bundle exec rspec spec/support_table_data_spec.rb  # Single file
+bundle exec rake appraisals          # Test against all ActiveRecord versions
+```
+
+Uses RSpec with in-memory SQLite database. Test models defined in [spec/models.rb](spec/models.rb), data files in `spec/data/`.
+
+### Testing Against Multiple ActiveRecord Versions
+
+The gem supports ActiveRecord 6.0-8.0. Uses Appraisal for multi-version testing:
+
+```bash
+bundle exec appraisal install        # Install all gemfiles
+bundle exec appraisal rspec          # Run specs against all versions
+```
+
+See `Appraisals` file and `gemfiles/` directory.
+
+### Code Style
+
+Uses Standard Ruby formatter:
+
+```bash
+bundle exec rake standard:fix        # Auto-fix style issues
+```
+
+## Critical Patterns
+
+### Named Instance Method Generation
+
+**Hash-based data files** trigger dynamic method generation. Example from [spec/data/colors/named_colors.yml](spec/data/colors/named_colors.yml):
+
+```yaml
+red:
+  id: 1
+  name: Red
+  value: 16711680
+```
+
+Generates:
+- `Color.red` → finds record by id
+- `color_instance.red?` → tests if `color_instance.id == 1`
+- `Color.red_id` → returns `1` (if `named_instance_attribute_helpers :id` defined)
+
+**Implementation**: See `define_support_table_named_instance_methods` in [lib/support_table_data.rb](lib/support_table_data.rb#L230-L265). Methods are generated using `class_eval` with string interpolation.
+
+### Custom Setters for Associations
+
+Support tables often reference other support tables via named instances. Pattern from [spec/models.rb](spec/models.rb#L72-L74):
+
+```ruby
+def group_name=(value)
+  self.group = Group.named_instance(value)
+end
+```
+
+Allows data files to reference related records by instance name instead of foreign keys.
+
+### Key Attribute Configuration
+
+By default, uses model's `primary_key`. Override for non-id keys:
+
+```ruby
+self.support_table_key_attribute = :name  # Use 'name' instead of 'id'
+```
+
+Key attributes cannot be updated—changing them creates new records.
+
+### Dependency Resolution
+
+`sync_all!` automatically resolves dependencies via `belongs_to` associations and loads tables in correct order. For complex cases (join tables, indirect dependencies), explicitly declare:
+
+```ruby
+support_table_dependency "OtherModel"
+```
+
+See [lib/support_table_data.rb](lib/support_table_data.rb#L219-L222) and dependency resolution logic.
+
+## Testing Conventions
+
+- **Test data isolation**: Each test deletes all records in `before` block ([spec/spec_helper.rb](spec/spec_helper.rb))
+- **Sync before assertions**: Tests call `sync_table_data!` or `sync_all!` before verifying records exist
+- **Multi-file merging**: Tests verify that multiple data files for same model merge correctly (see `Color` model with 5 data files)
+- **STI handling**: See `Polygon`/`Triangle`/`Rectangle` tests for Single Table Inheritance patterns
+
+## Common Pitfalls
+
+1. **Method name conflicts**: Named instance methods raise `ArgumentError` if method already exists. Instance names must match `/\A[a-z][a-z0-9_]+\z/`
+2. **Array vs hash data**: Only hash-keyed data generates named instance methods. Use arrays or underscore-prefixed keys (`_others`) for records without helpers
+3. **Protected instances**: Records in data files cannot be deleted via `destroy` (though this gem doesn't enforce it—see companion caching gem)
+4. **Transaction safety**: All sync operations wrapped in transactions; changes rollback on failure
+
+## Rails Integration
+
+In Rails apps, the gem automatically:
+- Sets `SupportTableData.data_directory` to `Rails.root/db/support_tables`
+- Provides `rake support_table_data:sync` task ([lib/tasks/support_table_data.rake](lib/tasks/support_table_data.rake))
+- Handles eager loading in both classic and Zeitwerk autoloaders
+
+## File References
+
+- Main module: [lib/support_table_data.rb](lib/support_table_data.rb)
+- Test models: [spec/models.rb](spec/models.rb) - comprehensive examples of patterns
+- Sync task: [lib/tasks/support_table_data.rake](lib/tasks/support_table_data.rake)
+- Architecture docs: [ARCHITECTURE.md](ARCHITECTURE.md) - detailed diagrams and design decisions
+
+## Version Compatibility
+
+- Ruby ≥ 2.5
+- ActiveRecord ≥ 6.0
+- Ruby 3.4+: Requires `csv` gem in Gemfile (removed from stdlib)

Appraisals

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+appraise "activerecord_8.1" do
+  gem "activerecord", "~> 8.1.0"
+  gem "sqlite3", "~> 2.9.0"
+end
+
 appraise "activerecord_8.0" do
   gem "activerecord", "~> 8.0.0"
   gem "sqlite3", "~> 2.5.0"

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.4.1
+
+### Added
+
+- The default data directory for support table data in Rails applications will be set to `db/support_tables`. This can also be overridden by setting the `config.support_table_data_directory` configuration option in the Rails application.
+- Added rake task `support_table_data:add_yard_docs` for Rails applications that will add YARD documentation to support table models for the named instance helpers.
+
 ## 1.4.0
 
 ### Fixed

VERSION

@@ -1 +1 @@
-1.4.0
+1.4.1

gemfiles/activerecord_8.1.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rspec", "~> 3.0"
+gem "rake"
+gem "sqlite3", "~> 2.9.0"
+gem "appraisal"
+gem "standard", "~>1.0"
+gem "pry-byebug"
+gem "yard"
+gem "csv"
+gem "activerecord", "~> 8.1.0"
+
+gemspec path: "../"

lib/support_table_data/documentation.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SupportTableData
+  class Documentation
+    # Create a new documentation generator for a configuration class.
+    #
+    # @param config_class [Class] The configuration 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 class_def_with_yard_docs
+      instance_names = klass.instance_names
+      return nil if instance_names.empty?
+
+      generate_yard_class(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
+        # Find the #{name} record from the database.
+        #
+        # @return [#{klass.name}] the #{name} record
+        # @raise [ActiveRecord::RecordNotFound] if the record does not exist
+        # @!method self.#{name}
+      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
+        # Check if this record is the #{name} record.
+        #
+        # @return [Boolean] true if this is the #{name} record, false otherwise
+        # @!method #{name}?
+      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
+        # Get the #{name} record's #{attribute_name}.
+        #
+        # @return [Object] the #{name} record's #{attribute_name}
+        # @!method #{name}_#{attribute_name}
+      YARD
+    end
+
+    private
+
+    attr_reader :klass
+
+    def generate_yard_class(instance_names)
+      return nil if instance_names.empty?
+
+      yard_lines = ["class #{klass.name}"]
+
+      # Generate docs for each named instance
+      instance_names.sort.each_with_index do |name, index|
+        yard_lines << "" unless index.zero?
+        instance_helper_yard_doc(name).each_line(chomp: true) { |line| yard_lines << "  #{line}" }
+        yard_lines << ""
+        predicate_helper_yard_doc(name).each_line(chomp: true) { |line| yard_lines << "  #{line}" }
+        klass.support_table_attribute_helpers.each do |attribute_name|
+          yard_lines << ""
+          attribute_helper_yard_doc(name, attribute_name).each_line(chomp: true) { |line| yard_lines << "  #{line}" }
+        end
+      end
+
+      yard_lines << "end"
+
+      yard_lines.join("\n")
+    end
+  end
+end

lib/support_table_data/railtie.rb

@@ -2,6 +2,12 @@
 
 module SupportTableData
   class Railtie < Rails::Railtie
+    config.support_table_data_directory = "db/support_tables"
+
+    initializer "support_table_data" do |app|
+      SupportTableData.data_directory ||= app.config.support_table_data_directory
+    end
+
     rake_tasks do
       load File.expand_path("../tasks/support_table_data.rake", __dir__)
     end

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,35 @@ namespace :support_table_data do
       SupportTableData.sync_all!
     end
   end
+
+  desc "Adds YARD documentation comments to models to document the named instance methods."
+  task add_yard_docs: :environment do
+    require_relative "../support_table_data/documentation"
+    require_relative "utils"
+
+    SupportTableData::Tasks::Utils.eager_load!
+
+    ActiveRecord::Base.descendants.each do |klass|
+      next unless klass.included_modules.include?(SupportTableData)
+      next if klass.instance_names.empty?
+
+      doc = SupportTableData::Documentation.new(klass)
+      class_def_with_docs = doc.class_def_with_yard_docs
+      next unless class_def_with_docs
+
+      file_path = SupportTableData::Tasks::Utils.model_file_path(klass)
+      next unless file_path&.file? && file_path.readable?
+
+      begin_comment = "# Begin autogenerated YARD docs"
+      end_comment = "# End autogenerated YARD docs"
+
+      file_contents = File.read(file_path)
+      updated_contents = file_contents.sub(/#{begin_comment}.*#{end_comment}/m, "").strip
+      updated_contents = "#{updated_contents}\n\n#{begin_comment}\n#{class_def_with_docs}\n#{end_comment}\n"
+      next if file_contents == updated_contents
+
+      File.write(file_path, updated_contents)
+      puts "Added YARD documentation to #{klass.name}."
+    end
+  end
 end

lib/tasks/utils.rb

@@ -0,0 +1,38 @@
+# 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
+
+        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