support_table_data 1.5.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fded73fcb55268fa76b155b9cb192667bbe535e4e11f0cf00f8c3b8536fe3ee
-  data.tar.gz: 9e06e50abcba73a18918a7fe8fa0168c93a2d0b39c0d1cfa03f1d512368632af
+  metadata.gz: '081b2612659ea90591ecf5fd7386acbb9d10dbd90c20301e12fba39d3d81e4b3'
+  data.tar.gz: b7d4960153f4799031127c8e2fb6ffaa5da49acc1e59833b64c9f417dd9d77df
 SHA512:
-  metadata.gz: c107aa8e78cfbdfe8fdafd1cc42bf2f25b90075f561e9a7933e643ec2773647f4f96cc047d4ed0b90f8b15cd50ffa1e1f282c7f3abc61e25d70c3fb5150a2958
-  data.tar.gz: 612b88d848c4eb101018bf2c643f8b76825e7bb22b459a6b5998a70238f9eb8627bbe7f6d8533b362b99300dcdce3a905bc3a22ca30c680ca03e4043c8837c7c
+  metadata.gz: e38a2f56f37888a737c8493ec0078666cf8a138415326946829c506a57fc81f5bc3e8407232e7bacbd82a5d0066d9513dd14340360e9d4179a3b1d51a7d69517
+  data.tar.gz: 569bbabe38749923686c5d9aa757851f6ba3fad64317f18e3fdb209aec9c714ed1f020a6c07a1588464d1ed9c129bb983ae25d5378ae324b0abee8e467e0fa96

data/CHANGELOG.md

@@ -4,6 +4,14 @@ 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.5.1
+
+### Added
+
+- YARD documentation tasks can now take an optional file path argument to add, verify, or remove documentation for a specific support table model instead of all models. For example, you can run `bundle exec rake support_table_data:yard_docs:add[app/models/color.rb]` to add documentation for the `Color` model.
+- Added comment in generated YARD documentation indicating the command to run to update them so that it's clear to users how to keep the documentation up to date.
+- Aliased `support_table_data:yard_docs` to `support_table_data:yard_docs:add` for convenience since adding the documentation is the most common action.
+
 ## 1.5.0
 
 ### Added

data/README.md

@@ -187,7 +187,9 @@ completed:
 
 #### Documenting Named Instance Helpers
 
-In a Rails application, you can add YARD documentation for the named instance helpers by running the rake task `support_table_data:yard_docs:add`. This will add YARD comments to your model classes for each of the named instance helper methods defined on the model. Adding this documentation will help IDEs provide better code completion and inline documentation for the helper methods and expose the methods to AI agents.
+In a Rails application, you can add YARD documentation for the named instance helpers by running the rake task `support_table_data:yard_docs`. This will add YARD comments to your model classes for each of the named instance helper methods defined on the model. Adding this documentation will help IDEs provide better code completion and inline documentation for the helper methods and expose the methods to AI agents.
+
+To update a single model file, pass an optional file path argument, for example: `bundle exec rake "support_table_data:yard_docs[app/models/status.rb]"`.
 
 The default behavior is to add the documentation comments at the end of the model class by reopening the class definition. If you prefer to have the documentation comments appear elsewhere in the file, you can add the following markers to your model class and the YARD documentation will be inserted between these markers.
 

data/VERSION

@@ -1 +1 @@
-1.5.0
+1.5.1

data/lib/support_table_data/documentation/source_file.rb

@@ -9,6 +9,7 @@ module SupportTableData
       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.
       #
@@ -53,6 +54,7 @@ module SupportTableData
 
           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
@@ -62,6 +64,7 @@ module SupportTableData
         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

data/lib/tasks/support_table_data.rake

@@ -23,14 +23,16 @@ namespace :support_table_data do
     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."
-    task add: :environment 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.each do |source_file|
+      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)
@@ -38,13 +40,13 @@ namespace :support_table_data do
       end
     end
 
-    desc "Removes YARD documentation comments added by support_table_data from models."
-    task remove: :environment do
+    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.each do |source_file|
+      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)
@@ -52,15 +54,15 @@ namespace :support_table_data do
       end
     end
 
-    desc "Verify that all the support table models have up to date YARD documentation for named instance methods."
-    task verify: :environment do
+    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.each do |source_file|
+      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
@@ -68,9 +70,13 @@ namespace :support_table_data do
       end
 
       if all_up_to_date
-        puts "All support table models have up to date YARD documentation."
+        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 rails support_table_data:yard_docs:add to update the documentation."
+        raise "Run bundle exec rake support_table_data:yard_docs to update the documentation."
       end
     end
   end

data/lib/tasks/utils.rb

@@ -18,14 +18,17 @@ module SupportTableData
           end
         end
 
-        # Return a hash mapping all models that include SupportTableData to their source file paths.
+        # 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
+        def support_table_sources(file_path = nil)
+          require_relative file_path if file_path
+
           sources = []
 
           ActiveRecord::Base.descendants.each do |klass|
-            next unless klass.included_modules.include?(SupportTableData)
+            next unless klass.include?(SupportTableData)
 
             begin
               next if klass.instance_names.empty?
@@ -34,13 +37,18 @@ module SupportTableData
               next
             end
 
-            file_path = SupportTableData::Tasks::Utils.model_file_path(klass)
-            next unless file_path&.file? && file_path.readable?
+            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, file_path)
+            sources << Documentation::SourceFile.new(klass, model_file_path)
           end
 
-          sources
+          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)

data/support_table_data.gemspec

@@ -19,6 +19,7 @@ Gem::Specification.new do |spec|
   # 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/app/models/status.rb

@@ -9,3 +9,112 @@ class Status < ApplicationRecord
 
   validates :code, presence: true, uniqueness: true
 end
+
+# Begin YARD docs for support_table_data
+# To update these docs, run `bundle exec rake support_table_data:yard_docs`
+class Status
+  # @!group Named Instances
+
+  # Find the named instance +active+ from the database.
+  #
+  # @!method self.active
+  # @return [Status]
+  # @raise [ActiveRecord::RecordNotFound] if the record does not exist
+  # @!visibility public
+
+  # Check if this record is the named instance +active+.
+  #
+  # @!method active?
+  # @return [Boolean]
+  # @!visibility public
+
+  # Get the name attribute from the data file
+  # for the named instance +active+.
+  #
+  # @!method self.active_name
+  # @return [Object]
+  # @!visibility public
+
+  # Find the named instance +canceled+ from the database.
+  #
+  # @!method self.canceled
+  # @return [Status]
+  # @raise [ActiveRecord::RecordNotFound] if the record does not exist
+  # @!visibility public
+
+  # Check if this record is the named instance +canceled+.
+  #
+  # @!method canceled?
+  # @return [Boolean]
+  # @!visibility public
+
+  # Get the name attribute from the data file
+  # for the named instance +canceled+.
+  #
+  # @!method self.canceled_name
+  # @return [Object]
+  # @!visibility public
+
+  # Find the named instance +completed+ from the database.
+  #
+  # @!method self.completed
+  # @return [Status]
+  # @raise [ActiveRecord::RecordNotFound] if the record does not exist
+  # @!visibility public
+
+  # Check if this record is the named instance +completed+.
+  #
+  # @!method completed?
+  # @return [Boolean]
+  # @!visibility public
+
+  # Get the name attribute from the data file
+  # for the named instance +completed+.
+  #
+  # @!method self.completed_name
+  # @return [Object]
+  # @!visibility public
+
+  # Find the named instance +failed+ from the database.
+  #
+  # @!method self.failed
+  # @return [Status]
+  # @raise [ActiveRecord::RecordNotFound] if the record does not exist
+  # @!visibility public
+
+  # Check if this record is the named instance +failed+.
+  #
+  # @!method failed?
+  # @return [Boolean]
+  # @!visibility public
+
+  # Get the name attribute from the data file
+  # for the named instance +failed+.
+  #
+  # @!method self.failed_name
+  # @return [Object]
+  # @!visibility public
+
+  # Find the named instance +pending+ from the database.
+  #
+  # @!method self.pending
+  # @return [Status]
+  # @raise [ActiveRecord::RecordNotFound] if the record does not exist
+  # @!visibility public
+
+  # Check if this record is the named instance +pending+.
+  #
+  # @!method pending?
+  # @return [Boolean]
+  # @!visibility public
+
+  # Get the name attribute from the data file
+  # for the named instance +pending+.
+  #
+  # @!method self.pending_name
+  # @return [Object]
+  # @!visibility public
+
+  # @!endgroup
+end
+# End YARD docs for support_table_data

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: support_table_data
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.1
 platform: ruby
 authors:
 - Brian Durand
@@ -43,7 +43,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- AGENTS.md
 - ARCHITECTURE.md
 - CHANGELOG.md
 - MIT-LICENSE.txt

data/AGENTS.md

@@ -1,140 +0,0 @@
-# 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 `id` column. 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)