support_table_data 1.5.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '081b2612659ea90591ecf5fd7386acbb9d10dbd90c20301e12fba39d3d81e4b3'
-  data.tar.gz: b7d4960153f4799031127c8e2fb6ffaa5da49acc1e59833b64c9f417dd9d77df
+  metadata.gz: 6aa6d124e04e60a539f6a56207da866bb6aa0d277484104f6685d9499b41d504
+  data.tar.gz: f3c9791bf9e6b2a46416cca2a154abdb1fe18e108f3e386670818939cabac1a2
 SHA512:
-  metadata.gz: e38a2f56f37888a737c8493ec0078666cf8a138415326946829c506a57fc81f5bc3e8407232e7bacbd82a5d0066d9513dd14340360e9d4179a3b1d51a7d69517
-  data.tar.gz: 569bbabe38749923686c5d9aa757851f6ba3fad64317f18e3fdb209aec9c714ed1f020a6c07a1588464d1ed9c129bb983ae25d5378ae324b0abee8e467e0fa96
+  metadata.gz: cec5bdca6906dac42489e2f43798bf647eebaf6fd1df1d314bb259cf46170c6f7833aeccd7f7d59917ea0406699f6cc99905afc5977bd907c1e19f750dc0b3e5
+  data.tar.gz: eb748280d59753b9bde5618900d0f25ae8e01c3ace0a37cdb5021cad1f1751832b14cc6e4bd624b200398178cd8bd3636e5d8d128c829180fe3c547d67ac88db

data/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.6.0
+
+### Added
+
+- Added `delete_missing` option to `sync_table_data!` and `sync_all!`. When set to `true`, any records in the database that are not defined in the data files will be deleted. This option defaults to `false` to preserve backward compatibility.
+- Each model can now choose how its YARD docs are generated by setting `self.support_table_yard_docs` to `:full` (the default — verbose comment block per method), `:compact` (shared `@!macro` definitions plus a short `@!method`/`@!macro` pair per method, dramatically reducing comment-block size on tables with many named instances), or `:none` (skip generation entirely; previously generated docs are stripped on the next run). IDEs and `yard doc` resolve the compact form into the same per-method documentation as the verbose form.
+- Attribute helper return types in the generated YARD and RBS docs are now inferred per method by inspecting the value the helper actually returns (`String`, `Integer`, `Boolean`, etc.) instead of the generic `Object`/`untyped`. Because the helpers return frozen literals from the parsed data file, the documentation tasks no longer require a database connection.
+- Added opt-in RBS signature generation. The new tasks `support_table_data:rbs`, `support_table_data:rbs:verify`, and `support_table_data:rbs:remove` write/check/delete `sig/<model_path>.rbs` files so the named instance helpers are visible to Ruby LSP, Steep, RubyMine, and other RBS-aware tools without polluting the model source files. The output directory can be overridden with `SupportTableData.rbs_signatures_path`.
+
+## 1.5.2
+
+### Added
+
+- Added `rubocop:disable all` around generated YARD documentation to prevent RuboCop offenses in the generated code. This ensures that the generated documentation does not cause any issues with RuboCop linting in the project.
+
 ## 1.5.1
 
 ### Added

data/README.md

@@ -189,7 +189,7 @@ completed:
 
 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]"`.
+To update a single model file, use the `add` task and pass an optional file path argument, for example: `bundle exec rake "support_table_data:yard_docs:add[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.
 
@@ -200,6 +200,30 @@ The default behavior is to add the documentation comments at the end of the mode
 
 A good practice is to add a check to your CI pipeline to ensure the documentation is always up to date. You can run the rake task `support_table_data:yard_docs:verify` to do this. It will exit with an error if any models do not have up to date documentation.
 
+Each model can choose how its YARD docs are generated by setting `support_table_yard_docs` to one of three values:
+
+- `:full` — verbose comment block per generated method (the default)
+- `:compact` — shared `@!macro` definitions at the top of the documentation block plus a short `@!method` / `@!macro` pair per generated method. IDEs and `yard doc` resolve the macros into the same per-method documentation as `:full`. Useful when a model has many named instances and the verbose comment block is too long to be useful inline.
+- `:none` — generate no YARD docs for this model. The rake task will also strip any previously generated YARD docs from the source file.
+
+```ruby
+class Feature < ApplicationRecord
+  include SupportTableData
+
+  self.support_table_yard_docs = :compact
+
+  add_support_table_data "features.yml"
+end
+```
+
+Attribute helper return types (`String`, `Integer`, `Boolean`, etc.) are inferred per method by inspecting the value the helper actually returns. The values come straight from the parsed data file, so the documentation tasks do not need a database connection to run.
+
+#### Generating RBS Signatures
+
+In addition to the inline YARD comments, you can generate [RBS](https://github.com/ruby/rbs) type signatures for the named instance helpers by running `bundle exec rake support_table_data:rbs`. This writes one `sig/<model_path>.rbs` file per model — for example a Rails model at `app/models/feature.rb` produces `sig/app/models/feature.rbs`. The signatures are picked up by Ruby LSP, Steep, RubyMine, and any other RBS-aware tool, and they keep the model source files free of generated content.
+
+Just like the YARD task, you can target a single file with `bundle exec rake "support_table_data:rbs:add[app/models/feature.rb]"`, verify they are up to date in CI with `support_table_data:rbs:verify`, and remove the generated files with `support_table_data:rbs:remove`. RBS generation is opt-in — running the YARD task alone does not produce RBS output, and vice versa.
+
 ### Caching
 
 You can use the companion [support_table_cache gem](https://github.com/bdurand/support_table_cache) to add caching support to your models. That way your application won't need to constantly query the database for records that will never change.
@@ -240,6 +264,21 @@ Status.sync_table_data!
 
 This will add any missing records to the table and update existing records so that the attributes in the table match the values in the data files. Records that do not appear in the data files will not be touched. Any attributes not specified in the data files will not be changed.
 
+If you want to remove records from the database that are no longer in the data files, you can pass `delete_missing: true`:
+
+```ruby
+Status.sync_table_data!(delete_missing: true)
+```
+
+This option can also be passed to `SupportTableData.sync_all!`:
+
+```ruby
+SupportTableData.sync_all!(delete_missing: true)
+```
+
+> [!CAUTION]
+> Use `delete_missing` with care. It will delete any records in the table that are not defined in the data files, which may include user-created data or fail due to foreign key constraints.
+
 The number of records contained in data files should be fairly small (ideally fewer than 100). It is possible to load just a subset of rows in a large table because only the rows listed in the data files will be synced. You can use this feature if your table allows user-entered data, but has a few rows that must exist for the code to work.
 
 Loading data is done inside a database transaction. No changes will be persisted to the database unless all rows for a model can be synced.
@@ -309,6 +348,20 @@ end
 
 You must also call `SupportTableData.sync_all!` before running your test suite. This method should be called in the test suite setup code after any data in the test database has been purged and before any tests are run.
 
+> [!TIP]
+> If you are using a truncation database cleaning strategy exclude the support tables from the tables that get truncated. Syncing data is much faster when the data is already in the database. You should use the `delete_missing` option to remove any records that are not in the data files instead of deleting all records before each test.
+
+```ruby
+# Excluding support tables from truncation in DatabaseCleaner configuration.
+RSpec.configure do |config|
+  config.before(:suite) do
+    support_tables = SupportTableData.support_table_classes.map(&:table_name)
+    DatabaseCleaner.clean_with(:truncation, except: support_tables)
+    SupportTableData.sync_all!(delete_missing: true)
+  end
+end
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/VERSION

@@ -1 +1 @@
-1.5.1
+1.6.0

data/lib/support_table_data/documentation/rbs_doc.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SupportTableData
+  module Documentation
+    # Generates RBS type signatures for the dynamically-defined named instance
+    # helper methods on a support table model.
+    class RbsDoc
+      # @param klass [Class] The model class to generate signatures for
+      def initialize(klass)
+        @klass = klass
+      end
+
+      # Render the full RBS file content for the model, including the class
+      # declaration. Returns nil when the model has no named instances.
+      #
+      # @return [String, nil]
+      def signatures
+        instance_names = klass.instance_names
+        return nil if instance_names.empty?
+
+        body_lines = []
+        instance_names.sort.each_with_index do |name, idx|
+          body_lines << "" unless idx.zero?
+          body_lines.concat(instance_signatures(name))
+        end
+
+        <<~RBS
+          # Generated by support_table_data - do not edit by hand.
+          # To update, run `bundle exec rake support_table_data:rbs`.
+          class #{klass.name}
+          #{body_lines.map { |line| line.empty? ? "" : "  #{line}" }.join("\n")}
+          end
+        RBS
+      end
+
+      private
+
+      attr_reader :klass
+
+      def instance_signatures(name)
+        lines = []
+        lines << "def self.#{name}: () -> #{klass.name}"
+        lines << "def #{name}?: () -> bool"
+        klass.support_table_attribute_helpers.each do |attribute_name|
+          return_type = TypeInference.rbs_type(TypeInference.value_type(klass, "#{name}_#{attribute_name}"))
+          lines << "def self.#{name}_#{attribute_name}: () -> #{return_type}"
+        end
+        lines
+      end
+    end
+  end
+end

data/lib/support_table_data/documentation/rbs_file.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module SupportTableData
+  module Documentation
+    # Manages reading/writing the per-model RBS signature file.
+    class RbsFile
+      attr_reader :klass, :source_path, :path
+
+      # @param klass [Class] The model class
+      # @param source_path [Pathname] The path to the model's source `.rb` file
+      def initialize(klass, source_path)
+        @klass = klass
+        @source_path = Pathname.new(source_path)
+        @path = self.class.signatures_path_for(@source_path)
+      end
+
+      # Compute where the RBS signatures should live for a given source file.
+      # Defaults to `<project_root>/sig/<source_path_minus_extension>.rbs`.
+      # The project root is found by walking upward looking for a `Gemfile` or
+      # `.git` directory; if neither is found, the immediate parent of the
+      # source file is used.
+      #
+      # @param source_path [Pathname]
+      # @return [Pathname]
+      def self.signatures_path_for(source_path)
+        if SupportTableData.rbs_signatures_path
+          base = Pathname.new(SupportTableData.rbs_signatures_path)
+          relative = relative_to_project_root(source_path)
+          return base.join("#{relative.to_s.sub(/\.rb\z/, "")}.rbs")
+        end
+
+        root = project_root_for(source_path)
+        relative = source_path.expand_path.relative_path_from(root)
+        root.join("sig", "#{relative.to_s.sub(/\.rb\z/, "")}.rbs")
+      end
+
+      # Project root is the nearest ancestor directory containing a Gemfile or
+      # a .git directory. Falls back to the source file's directory.
+      def self.project_root_for(source_path)
+        current = Pathname.new(source_path).expand_path.parent
+        loop do
+          return current if current.join("Gemfile").file?
+          return current if current.join(".git").exist?
+
+          parent = current.parent
+          return Pathname.new(source_path).expand_path.parent if parent == current
+
+          current = parent
+        end
+      end
+
+      def self.relative_to_project_root(source_path)
+        Pathname.new(source_path).expand_path.relative_path_from(project_root_for(source_path))
+      end
+
+      # Render the desired RBS content for this model, or nil if the model has
+      # no named instances (in which case no file should be written).
+      #
+      # @return [String, nil]
+      def signatures_content
+        RbsDoc.new(klass).signatures
+      end
+
+      # Whether the existing on-disk file matches what would be generated.
+      #
+      # @return [Boolean]
+      def up_to_date?
+        desired = signatures_content
+        if desired.nil?
+          !path.file?
+        else
+          path.file? && path.read == desired
+        end
+      end
+
+      # Write the generated RBS content to disk, creating parent directories as
+      # needed. Returns true if the file was written, false if there was nothing
+      # to write.
+      #
+      # @return [Boolean]
+      def write!
+        content = signatures_content
+        return false if content.nil?
+
+        path.parent.mkpath
+        path.write(content)
+        true
+      end
+
+      # Delete the generated RBS file if it exists. Returns true if a file was
+      # removed.
+      #
+      # @return [Boolean]
+      def remove!
+        return false unless path.file?
+
+        path.delete
+        true
+      end
+    end
+  end
+end

data/lib/support_table_data/documentation/source_file.rb

@@ -44,7 +44,9 @@ module SupportTableData
       # @return [String]
       def source_with_yard_docs
         yard_docs = YardDoc.new(klass).named_instance_yard_docs
-        return source if yard_docs.nil?
+        if yard_docs.nil?
+          return has_yard_docs? ? source_without_yard_docs : source
+        end
 
         existing_yard_docs = source.match(YARD_COMMENT_REGEX)
         if existing_yard_docs
@@ -55,9 +57,11 @@ 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}# rubocop:disable all\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}# rubocop:enable all"
           updated_source << "\n#{indent}#{END_YARD_COMMENT}"
           updated_source << source[existing_yard_docs.end(0)..-1]
           updated_source
@@ -65,9 +69,11 @@ module SupportTableData
           yard_comments = <<~SOURCE.chomp("\n")
             #{BEGIN_YARD_COMMENT}
             #{UPDATE_COMMAND_COMMENT}
+            # rubocop:disable all
             class #{klass.name}
             #{yard_docs.lines.map { |line| line.blank? ? "\n" : "  #{line}" }.join}
             end
+            # rubocop:enable all
             #{END_YARD_COMMENT}
           SOURCE
           "#{source.rstrip}\n\n#{yard_comments}#{trailing_newline}"

data/lib/support_table_data/documentation/type_inference.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module SupportTableData
+  module Documentation
+    # Infers documentation types for the dynamically-defined attribute helpers
+    # by calling the generated method and inspecting the class of the value
+    # it returns. The values returned by these helpers are frozen literals from
+    # the parsed data file, so this does not require a database connection.
+    #
+    # This module must not be used on finder helpers (e.g. `Color.red`), which
+    # call `find_by!` and would hit the database.
+    module TypeInference
+      module_function
+
+      # Determine the documentation type for an attribute helper by calling
+      # the method and looking at the class of the returned value. Returns
+      # nil when the method is not defined.
+      #
+      # @param klass [Class] The model class
+      # @param method_name [String, Symbol] The class method name to call
+      # @return [Class, nil]
+      def value_type(klass, method_name)
+        return nil unless klass.respond_to?(method_name)
+
+        klass.public_send(method_name).class
+      end
+
+      # Map a Ruby value class to a YARD type string.
+      def yard_type(value_class)
+        case value_class&.name
+        when "String" then "String"
+        when "Integer" then "Integer"
+        when "Float" then "Float"
+        when "TrueClass", "FalseClass" then "Boolean"
+        when "Array" then "Array"
+        when "Hash" then "Hash"
+        when "NilClass", nil then "Object"
+        else value_class.name
+        end
+      end
+
+      # Map a Ruby value class to an RBS type string.
+      def rbs_type(value_class)
+        case value_class&.name
+        when "String" then "String"
+        when "Integer" then "Integer"
+        when "Float" then "Float"
+        when "TrueClass", "FalseClass" then "bool"
+        when "Array" then "Array[untyped]"
+        when "Hash" then "Hash[untyped, untyped]"
+        when "NilClass", nil then "untyped"
+        else value_class.name
+        end
+      end
+    end
+  end
+end

data/lib/support_table_data/documentation/yard_doc.rb

@@ -3,17 +3,38 @@
 module SupportTableData
   module Documentation
     class YardDoc
+      MACRO_FINDER = "support_table_data_finder"
+      MACRO_PREDICATE = "support_table_data_predicate"
+      MACRO_ATTRIBUTE = "support_table_data_attribute"
+
       # @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.
+      # Generate YARD documentation for the model's helper methods. The format
+      # is controlled by the model's `support_table_yard_docs` setting:
+      #
+      # * `:full`    - verbose comment block per method (default)
+      # * `:compact` - shared @!macro definitions plus a short @!method/@!macro
+      #                pair per generated method
+      # * `:none`    - generate no docs at all
       #
-      # @return [String, nil] The YARD documentation class definition, or nil if no named instances
+      # @return [String, nil] The YARD documentation, or nil if no docs should
+      #   be emitted (either because the model has no named instances or because
+      #   `support_table_yard_docs` is `:none`).
       def named_instance_yard_docs
+        return nil if klass.support_table_yard_docs == :none
+
         instance_names = klass.instance_names
-        generate_yard_docs(instance_names)
+        return nil if instance_names.empty?
+
+        case klass.support_table_yard_docs
+        when :compact
+          generate_compact_yard_docs(instance_names)
+        else
+          generate_verbose_yard_docs(instance_names)
+        end
       end
 
       # Generate YARD documentation comment for named instance singleton method.
@@ -48,14 +69,16 @@ module SupportTableData
       # Generate YARD documentation comment for the attribute method helper for the named instance.
       #
       # @param name [String] The name of the instance method.
+      # @param attribute_name [String] The attribute being read.
       # @return [String] The YARD comment text
       def attribute_helper_yard_doc(name, attribute_name)
+        return_type = attribute_yard_return_type(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]
+          # @return [#{return_type}]
           # @!visibility public
         YARD
       end
@@ -64,12 +87,9 @@ module SupportTableData
 
       attr_reader :klass
 
-      def generate_yard_docs(instance_names)
-        return nil if instance_names.empty?
-
+      def generate_verbose_yard_docs(instance_names)
         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)
@@ -86,6 +106,77 @@ module SupportTableData
 
         yard_lines.join("\n")
       end
+
+      def generate_compact_yard_docs(instance_names)
+        yard_lines = ["# @!group Named Instances"]
+        yard_lines << ""
+        yard_lines << compact_preamble
+        yard_lines << ""
+        yard_lines << compact_macro_definitions
+
+        instance_names.sort.each do |name|
+          yard_lines << ""
+          yard_lines << compact_instance_block(name)
+        end
+
+        yard_lines << ""
+        yard_lines << "# @!endgroup"
+
+        yard_lines.join("\n")
+      end
+
+      def compact_preamble
+        <<~YARD.chomp("\n")
+          # The methods in this group are dynamically defined by support_table_data
+          # for each named instance in the data file. The macros below are the
+          # documentation templates; the per-instance @!method lines that follow
+          # invoke them with the instance name (and attribute name, where applicable).
+        YARD
+      end
+
+      def compact_macro_definitions
+        attribute_macro = <<~YARD.chomp("\n")
+          # @!macro [new] #{MACRO_ATTRIBUTE}
+          #   Get the +$2+ attribute from the data file for the named instance +$1+.
+          #   @return [$3]
+          #   @!visibility public
+        YARD
+
+        finder_macro = <<~YARD.chomp("\n")
+          # @!macro [new] #{MACRO_FINDER}
+          #   Find the named instance +$1+ from the database.
+          #   @return [#{klass.name}]
+          #   @raise [ActiveRecord::RecordNotFound] if the record does not exist
+          #   @!visibility public
+        YARD
+
+        predicate_macro = <<~YARD.chomp("\n")
+          # @!macro [new] #{MACRO_PREDICATE}
+          #   Check if this record is the named instance +$1+.
+          #   @return [Boolean]
+          #   @!visibility public
+        YARD
+
+        [finder_macro, "", predicate_macro, "", attribute_macro].join("\n")
+      end
+
+      def compact_instance_block(name)
+        lines = []
+        lines << "# @!method self.#{name}"
+        lines << "# @!macro #{MACRO_FINDER} #{name}"
+        lines << "# @!method #{name}?"
+        lines << "# @!macro #{MACRO_PREDICATE} #{name}"
+        klass.support_table_attribute_helpers.each do |attribute_name|
+          return_type = attribute_yard_return_type(name, attribute_name)
+          lines << "# @!method self.#{name}_#{attribute_name}"
+          lines << "# @!macro #{MACRO_ATTRIBUTE} #{name} #{attribute_name} #{return_type}"
+        end
+        lines.join("\n")
+      end
+
+      def attribute_yard_return_type(name, attribute_name)
+        TypeInference.yard_type(TypeInference.value_type(klass, "#{name}_#{attribute_name}"))
+      end
     end
   end
 end

data/lib/support_table_data/documentation.rb

@@ -2,8 +2,10 @@
 
 module SupportTableData
   module Documentation
+    autoload :TypeInference, File.expand_path("documentation/type_inference", __dir__)
+    autoload :SourceFile, File.expand_path("documentation/source_file", __dir__)
+    autoload :YardDoc, File.expand_path("documentation/yard_doc", __dir__)
+    autoload :RbsDoc, File.expand_path("documentation/rbs_doc", __dir__)
+    autoload :RbsFile, File.expand_path("documentation/rbs_file", __dir__)
   end
 end
-
-require_relative "documentation/source_file"
-require_relative "documentation/yard_doc"

data/lib/{tasks → support_table_data/tasks}/utils.rb

@@ -23,7 +23,8 @@ module 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
+          file_path = Pathname.new(file_path) if file_path.is_a?(String)
+          require file_path.expand_path if file_path
 
           sources = []
 
@@ -51,6 +52,16 @@ module SupportTableData
           []
         end
 
+        # Return RBS file handlers for all support table models.
+        #
+        # @param file_path [String, Pathname, nil] Optional file path to filter by.
+        # @return [Array<SupportTableData::Documentation::RbsFile>]
+        def support_table_rbs_files(file_path = nil)
+          support_table_sources(file_path).map do |source|
+            Documentation::RbsFile.new(source.klass, source.path)
+          end
+        end
+
         def model_file_path(klass)
           file_path = "#{klass.name.underscore}.rb"
           model_path = nil

data/lib/support_table_data/tasks.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SupportTableData
+  module Tasks
+    autoload :Utils, File.expand_path("tasks/utils", __dir__)
+  end
+end

data/lib/support_table_data.rb

@@ -8,7 +8,14 @@
 module SupportTableData
   extend ActiveSupport::Concern
 
+  autoload :ValidationError, File.expand_path("support_table_data/validation_error", __dir__)
+  autoload :Documentation, File.expand_path("support_table_data/documentation", __dir__)
+  autoload :Tasks, File.expand_path("support_table_data/tasks", __dir__)
+
+  YARD_DOC_OPTIONS = [:full, :compact, :none].freeze
+
   @data_directory = nil
+  @rbs_signatures_path = nil
 
   included do
     # Internal variables used for memoization.
@@ -31,6 +38,15 @@ module SupportTableData
     # value set by SupportTableData.data_directory. This is only used if relative paths are passed
     # in to add_support_table_data.
     class_attribute :support_table_data_directory, instance_accessor: false
+
+    # Private class attribute backing `support_table_yard_docs`. Use the public
+    # accessor to read/write.
+    # @private
+    class_attribute :_support_table_yard_docs, instance_accessor: false, default: :full
+    class << self
+      private :_support_table_yard_docs=
+      private :_support_table_yard_docs
+    end
   end
 
   class_methods do
@@ -48,12 +64,39 @@ module SupportTableData
       _support_table_key_attribute || "id"
     end
 
+    # Get the YARD documentation mode for this model. One of:
+    #
+    # * `:full`    - emit a verbose comment block per generated method (default)
+    # * `:compact` - emit shared @!macro definitions plus a short
+    #                @!method/@!macro pair per generated method
+    # * `:none`    - generate no YARD docs for this model; the rake task will
+    #                strip any existing generated YARD docs
+    #
+    # @return [Symbol]
+    def support_table_yard_docs
+      _support_table_yard_docs
+    end
+
+    # Set the YARD documentation mode for this model. See `support_table_yard_docs`
+    # for the supported values.
+    #
+    # @param value [Symbol]
+    # @return [void]
+    def support_table_yard_docs=(value)
+      unless SupportTableData::YARD_DOC_OPTIONS.include?(value)
+        raise ArgumentError, "support_table_yard_docs must be one of #{SupportTableData::YARD_DOC_OPTIONS.inspect} (got #{value.inspect})"
+      end
+      self._support_table_yard_docs = value
+    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.
+    # `add_support_table_data`. By default, rows that are no longer present in the data files
+    # will not be deleted unless `delete_missing` is enabled.
     #
+    # @param delete_missing [Boolean] If true, then any records in the database that are not in the data
+    #   files will be deleted. Use with caution.
     # @return [Array<Hash>] List of saved changes for each record that was created or modified.
-    def sync_table_data!
+    def sync_table_data!(delete_missing: false)
       return unless table_exists?
 
       canonical_data = support_table_data.each_with_object({}) do |attributes, hash|
@@ -64,6 +107,8 @@ module SupportTableData
 
       begin
         ActiveSupport::Notifications.instrument("support_table_data.sync", class: self) do
+          synced_ids = []
+
           transaction do
             records.each do |record|
               key = record[support_table_key_attribute].to_s
@@ -75,6 +120,8 @@ module SupportTableData
                 changes << record.changes
                 record.save!
               end
+
+              synced_ids << record.id if attributes
             end
 
             canonical_data.each_value do |attributes|
@@ -86,6 +133,11 @@ module SupportTableData
               end
               changes << record.changes
               record.save!
+              synced_ids << record.id
+            end
+
+            if delete_missing
+              where.not(primary_key => synced_ids).destroy_all
             end
           end
         end
@@ -373,6 +425,14 @@ module SupportTableData
       @data_directory = value&.to_s
     end
 
+    # Override the directory under which generated RBS signature files are
+    # written. When nil (the default) signatures go to
+    # `<project_root>/sig/<model_path>.rbs`, where the project root is the
+    # nearest ancestor directory containing a Gemfile or .git directory.
+    #
+    # @return [String, Pathname, nil]
+    attr_accessor :rbs_signatures_path
+
     # Sync all support table classes. Classes must already be loaded in order to be synced.
     #
     # You can pass in a list of classes that you want to ensure are synced. This feature
@@ -382,11 +442,13 @@ module SupportTableData
     # when the test suite is initializing.
     #
     # @param extra_classes [Class] List of classes to force into the detected list of classes to sync.
+    # @param delete_missing [Boolean] If true, then any records in the database that are not in the data
+    #   files will be deleted from each table. Use with caution.
     # @return [Hash<Class, Array<Hash>] Hash of classes synced with a list of saved changes.
-    def sync_all!(*extra_classes)
+    def sync_all!(*extra_classes, delete_missing: false)
       changes = {}
       support_table_classes(*extra_classes).each do |klass|
-        changes[klass] = klass.sync_table_data!
+        changes[klass] = klass.sync_table_data!(delete_missing: delete_missing)
       end
       changes
     end
@@ -483,8 +545,6 @@ 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

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 
 namespace :support_table_data do
-  desc "Syncronize data for all models that include SupportTableData."
+  desc "Synchronize data for all models that include SupportTableData."
   task sync: :environment do
-    require_relative "utils"
-
     SupportTableData::Tasks::Utils.eager_load!
 
     logger_callback = lambda do |name, started, finished, unique_id, payload|
@@ -23,14 +21,12 @@ namespace :support_table_data do
     end
   end
 
+  desc "Adds YARD documentation comments to all support table models to document the named instance methods."
   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?
@@ -42,9 +38,6 @@ namespace :support_table_data 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(args[:file_path]).each do |source_file|
         next unless source_file.has_yard_docs?
@@ -56,9 +49,6 @@ namespace :support_table_data 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
@@ -80,4 +70,53 @@ namespace :support_table_data do
       end
     end
   end
+
+  desc "Generates RBS signature files for named instance methods in all support table models."
+  task rbs: "rbs:add"
+
+  namespace :rbs do
+    desc "Generates RBS signature files for named instance methods. Optional arg: file_path"
+    task :add, [:file_path] => :environment do |_task, args|
+      SupportTableData::Tasks::Utils.eager_load!
+      SupportTableData::Tasks::Utils.support_table_rbs_files(args[:file_path]).each do |rbs_file|
+        next if rbs_file.up_to_date?
+
+        rbs_file.write!
+        puts "Wrote RBS signatures for #{rbs_file.klass.name} to #{rbs_file.path}."
+      end
+    end
+
+    desc "Removes generated RBS signature files. Optional arg: file_path"
+    task :remove, [:file_path] => :environment do |_task, args|
+      SupportTableData::Tasks::Utils.eager_load!
+      SupportTableData::Tasks::Utils.support_table_rbs_files(args[:file_path]).each do |rbs_file|
+        next unless rbs_file.remove!
+
+        puts "Removed RBS signatures for #{rbs_file.klass.name} (#{rbs_file.path})."
+      end
+    end
+
+    desc "Verify that generated RBS signature files are up to date. Optional arg: file_path"
+    task :verify, [:file_path] => :environment do |_task, args|
+      SupportTableData::Tasks::Utils.eager_load!
+
+      all_up_to_date = true
+      SupportTableData::Tasks::Utils.support_table_rbs_files(args[:file_path]).each do |rbs_file|
+        unless rbs_file.up_to_date?
+          puts "RBS signatures are not up to date for #{rbs_file.klass.name} (#{rbs_file.path})."
+          all_up_to_date = false
+        end
+      end
+
+      if all_up_to_date
+        if args[:file_path]
+          puts "RBS signatures are up to date for #{args[:file_path]}."
+        else
+          puts "All support table models have up to date RBS signatures."
+        end
+      else
+        raise "Run bundle exec rake support_table_data:rbs to update the signatures."
+      end
+    end
+  end
 end

data/support_table_data.gemspec

@@ -27,6 +27,7 @@ Gem::Specification.new do |spec|
     bin/
     gemfiles/
     spec/
+    test_app/
   ]
   spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
     `git ls-files -z`.split("\x0").reject { |f| ignore_files.any? { |path| f.start_with?(path) } }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: support_table_data
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.6.0
 platform: ruby
 authors:
 - Brian Durand
@@ -50,36 +50,17 @@ files:
 - VERSION
 - lib/support_table_data.rb
 - lib/support_table_data/documentation.rb
+- lib/support_table_data/documentation/rbs_doc.rb
+- lib/support_table_data/documentation/rbs_file.rb
 - lib/support_table_data/documentation/source_file.rb
+- lib/support_table_data/documentation/type_inference.rb
 - lib/support_table_data/documentation/yard_doc.rb
 - lib/support_table_data/railtie.rb
+- lib/support_table_data/tasks.rb
+- lib/support_table_data/tasks/utils.rb
 - lib/support_table_data/validation_error.rb
 - lib/tasks/support_table_data.rake
-- lib/tasks/utils.rb
 - support_table_data.gemspec
-- test_app/.gitignore
-- test_app/Gemfile
-- test_app/Rakefile
-- test_app/app/models/application_record.rb
-- test_app/app/models/secondary_application_record.rb
-- test_app/app/models/status.rb
-- test_app/app/models/thing.rb
-- test_app/bin/rails
-- test_app/config.ru
-- test_app/config/application.rb
-- test_app/config/boot.rb
-- test_app/config/database.yml
-- test_app/config/environment.rb
-- test_app/config/environments/development.rb
-- test_app/config/environments/test.rb
-- test_app/db/migrate/20260103060951_create_status.rb
-- test_app/db/schema.rb
-- test_app/db/secondary_migrate/20260104000001_create_things.rb
-- test_app/db/secondary_schema.rb
-- test_app/db/support_tables/statuses.yml
-- test_app/db/support_tables/things.yml
-- test_app/lib/tasks/database.rake
-- test_app/log/.keep
 homepage: https://github.com/bdurand/support_table_data
 licenses:
 - MIT
@@ -101,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Extension for ActiveRecord models to manage synchronizing data in support/lookup
   tables across environments. Also provides the ability to directly reference and

data/test_app/.gitignore

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

data/test_app/Gemfile

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

data/test_app/Rakefile

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

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

data/test_app/app/models/secondary_application_record.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-class SecondaryApplicationRecord < ApplicationRecord
-  self.abstract_class = true
-
-  connects_to database: {writing: :secondary, reading: :secondary}
-end

data/test_app/app/models/status.rb

@@ -1,120 +0,0 @@
-# frozen_string_literal: true
-
-class Status < ApplicationRecord
-  include SupportTableData
-
-  self.support_table_key_attribute = :code
-  add_support_table_data "statuses.yml"
-  named_instance_attribute_helpers :name
-
-  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

data/test_app/app/models/thing.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-class Thing < SecondaryApplicationRecord
-  include SupportTableData
-
-  self.support_table_key_attribute = :id
-  add_support_table_data "things.yml"
-
-  validates :name, presence: true, uniqueness: true
-end

data/test_app/bin/rails

@@ -1,4 +0,0 @@
-#!/usr/bin/env ruby
-APP_PATH = File.expand_path("../config/application", __dir__)
-require_relative "../config/boot"
-require "rails/commands"

data/test_app/config/application.rb

@@ -1,42 +0,0 @@
-require_relative "boot"
-
-require "rails"
-# Pick the frameworks you want:
-# require "active_model/railtie"
-# require "active_job/railtie"
-require "active_record/railtie"
-# require "active_storage/engine"
-# require "action_controller/railtie"
-# require "action_mailer/railtie"
-# require "action_mailbox/engine"
-# require "action_text/engine"
-# require "action_view/railtie"
-# require "action_cable/engine"
-# require "rails/test_unit/railtie"
-
-# Require the gems listed in Gemfile, including any gems
-# you've limited to :test, :development, or :production.
-Bundler.require(*Rails.groups)
-
-module TestApp
-  class Application < Rails::Application
-    # Initialize configuration defaults for originally generated Rails version.
-    config.load_defaults 8.1
-
-    # Please, add to the `ignore` list any other `lib` subdirectories that do
-    # not contain `.rb` files, or that should not be reloaded or eager loaded.
-    # Common ones are `templates`, `generators`, or `middleware`, for example.
-    config.autoload_lib(ignore: %w[assets tasks])
-
-    # Configuration for the application, engines, and railties goes here.
-    #
-    # These settings can be overridden in specific environments using the files
-    # in config/environments, which are processed later.
-    #
-    # config.time_zone = "Central Time (US & Canada)"
-    config.eager_load_paths << Rails.root.join("app", "configurations")
-
-    # Don't generate system test files.
-    config.generators.system_tests = nil
-  end
-end

data/test_app/config/boot.rb

@@ -1,3 +0,0 @@
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
-
-require "bundler/setup" # Set up gems listed in the Gemfile.

data/test_app/config/database.yml

@@ -1,17 +0,0 @@
-development:
-  primary:
-    adapter: sqlite3
-    database: db/development.sqlite3
-  secondary:
-    adapter: sqlite3
-    database: db/secondary_development.sqlite3
-    migrations_paths: db/secondary_migrate
-
-test:
-  primary:
-    adapter: sqlite3
-    database: db/test.sqlite3
-  secondary:
-    adapter: sqlite3
-    database: db/secondary_test.sqlite3
-    migrations_paths: db/secondary_migrate

data/test_app/config/environment.rb

@@ -1,5 +0,0 @@
-# Load the Rails application.
-require_relative "application"
-
-# Initialize the Rails application.
-Rails.application.initialize!

data/test_app/config/environments/development.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-Rails.application.configure do
-  # Settings specified here will take precedence over those in config/application.rb.
-
-  # Make code changes take effect immediately without server restart.
-  config.enable_reloading = true
-
-  # Do not eager load code on boot.
-  config.eager_load = false
-end

data/test_app/config/environments/test.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-Rails.application.configure do
-  # Settings specified here will take precedence over those in config/application.rb.
-
-  # Make code changes take effect immediately without server restart.
-  config.enable_reloading = true
-
-  # Do not eager load code on boot.
-  config.eager_load = false
-end

data/test_app/config.ru

@@ -1,6 +0,0 @@
-# This file is used by Rack-based servers to start the application.
-
-require_relative "config/environment"
-
-# run Rails.application
-# Rails.application.load_server

data/test_app/db/migrate/20260103060951_create_status.rb

@@ -1,8 +0,0 @@
-class CreateStatus < ActiveRecord::Migration[8.1]
-  def change
-    create_table :statuses do |t|
-      t.string :code, null: false, index: {unique: true}
-      t.string :name, null: false, index: {unique: true}
-    end
-  end
-end

data/test_app/db/schema.rb

@@ -1,20 +0,0 @@
-# This file is auto-generated from the current state of the database. Instead
-# of editing this file, please use the migrations feature of Active Record to
-# incrementally modify your database, and then regenerate this schema definition.
-#
-# This file is the source Rails uses to define your schema when running `bin/rails
-# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
-# be faster and is potentially less error prone than running all of your
-# migrations from scratch. Old migrations may fail to apply correctly if those
-# migrations use external dependencies or application code.
-#
-# It's strongly recommended that you check this file into your version control system.
-
-ActiveRecord::Schema[8.1].define(version: 2026_01_03_060951) do
-  create_table "statuses", force: :cascade do |t|
-    t.string "code", null: false
-    t.string "name", null: false
-    t.index ["code"], name: "index_statuses_on_code", unique: true
-    t.index ["name"], name: "index_statuses_on_name", unique: true
-  end
-end

data/test_app/db/secondary_migrate/20260104000001_create_things.rb

@@ -1,7 +0,0 @@
-class CreateThings < ActiveRecord::Migration[8.1]
-  def change
-    create_table :things do |t|
-      t.string :name, null: false, index: {unique: true}
-    end
-  end
-end

data/test_app/db/secondary_schema.rb

@@ -1,25 +0,0 @@
-# This file is auto-generated from the current state of the database. Instead
-# of editing this file, please use the migrations feature of Active Record to
-# incrementally modify your database, and then regenerate this schema definition.
-#
-# This file is the source Rails uses to define your schema when running `bin/rails
-# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
-# be faster and is potentially less error prone than running all of your
-# migrations from scratch. Old migrations may fail to apply correctly if those
-# migrations use external dependencies or application code.
-#
-# It's strongly recommended that you check this file into your version control system.
-
-ActiveRecord::Schema[8.1].define(version: 2026_01_04_000001) do
-  create_table "statuses", force: :cascade do |t|
-    t.string "code", null: false
-    t.string "name", null: false
-    t.index ["code"], name: "index_statuses_on_code", unique: true
-    t.index ["name"], name: "index_statuses_on_name", unique: true
-  end
-
-  create_table "things", force: :cascade do |t|
-    t.string "name", null: false
-    t.index ["name"], name: "index_things_on_name", unique: true
-  end
-end

data/test_app/db/support_tables/statuses.yml

@@ -1,19 +0,0 @@
-pending:
-  code: pending
-  name: Pending
-
-active:
-  code: active
-  name: Active
-
-completed:
-  code: completed
-  name: Completed
-
-canceled:
-  code: canceled
-  name: Canceled
-
-failed:
-  code: failed
-  name: Failed

data/test_app/db/support_tables/things.yml

@@ -1,5 +0,0 @@
-- id: 1
-  name: Thing One
-
-- id: 2
-  name: Thing Two

data/test_app/lib/tasks/database.rake

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-if Rake::Task.task_defined?("db:migrate")
-  Rake::Task["db:migrate"].enhance do
-    # The main database connection may have artifacts from the migration, so re-establish it
-    # to get a clean connection before syncing support table data.
-    ActiveRecord::Base.establish_connection
-
-    Rake::Task["support_table_data:sync"].invoke
-  end
-end