annotaterb 4.18.0 → 4.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0276a5044aa1b444f73aac5612004ce9a8c05c6d47634fb2e8798c24a442fed5
-  data.tar.gz: 58cd27cb187989b06c459979ac0152db9dfdb54d671b9348980c244caa7981a6
+  metadata.gz: 9df7cea27e60968dc415cd65fc55696bfcb47444bdb0dc9964ce155bfbce4e40
+  data.tar.gz: 6883710db1dd58633c3a349adec97257df9c2d809a220fd19ba90c2a4a584cb7
 SHA512:
-  metadata.gz: ac0f491e7022299fc96029950c5edf2b0e05aa38e9f3198ec37acbd04275888be493f4202f31295e8db0ad7737cc03d2c6b52e5fbb51c24418ef92f40da77a13
-  data.tar.gz: 914216a38c137682acb6e2b58154c3af47dba3b0ebb424b69194a59c3939cfdd01c00d0f75a10bb51800f2ea6ce3f4dc97f3cdcd592ff7f77e7cafc906cd660f
+  metadata.gz: 2e164027db851243b7a1fccf9590c4a7515f47454ec785070e8e1dcd71bc0de7bec2caea30d919e6497dedfe78180681828cd6f1e24c6f0539c1d4e6b7895c33
+  data.tar.gz: 65629d818e0f3a92528deec50d5ba6adeb4a521058a174a7d463df1d565a8bf59eccd4ddb039ea68fe0dffed7329a994a5fbc1dae9cf19cb87cf9dcec7e308f2

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [v4.19.0](https://github.com/drwl/annotaterb/tree/v4.19.0) (2025-08-28)
+
+[Full Changelog](https://github.com/drwl/annotaterb/compare/v4.18.0...v4.19.0)
+
+**Implemented enhancements:**
+
+- ignore ActiveRecord::AssociatedObject [\#172](https://github.com/drwl/annotaterb/issues/172)
+
+**Closed issues:**
+
+- STI classes blank [\#252](https://github.com/drwl/annotaterb/issues/252)
+- Model annotation issue [\#249](https://github.com/drwl/annotaterb/issues/249)
+
+**Merged pull requests:**
+
+- Bump version to v4.19.0 [\#259](https://github.com/drwl/annotaterb/pull/259) ([drwl](https://github.com/drwl))
+- Fix STI models not being annotated [\#256](https://github.com/drwl/annotaterb/pull/256) ([drwl](https://github.com/drwl))
+- refactor: relocate migration\_version\_for\_model method to ModelWrapper [\#255](https://github.com/drwl/annotaterb/pull/255) ([OdenTakashi](https://github.com/OdenTakashi))
+- Fix: Skip abstract models during annotation [\#253](https://github.com/drwl/annotaterb/pull/253) ([taise](https://github.com/taise))
+- Fix Ruby 3.3.8 compatibility and improve Zeitwerk support for non-Rails projects [\#250](https://github.com/drwl/annotaterb/pull/250) ([bradley2W1DL](https://github.com/bradley2W1DL))
+- Return a model files array even if it’s empty [\#248](https://github.com/drwl/annotaterb/pull/248) ([Flink](https://github.com/Flink))
+- Generate changelog for v4.18.0 [\#247](https://github.com/drwl/annotaterb/pull/247) ([drwl](https://github.com/drwl))
+
+## [v4.18.0](https://github.com/drwl/annotaterb/tree/v4.18.0) (2025-08-04)
+
+[Full Changelog](https://github.com/drwl/annotaterb/compare/v4.17.0...v4.18.0)
+
+**Implemented enhancements:**
+
+- Feature request: support for multi database [\#188](https://github.com/drwl/annotaterb/issues/188)
+
+**Closed issues:**
+
+- Does not run on rollback with multiple databases [\#244](https://github.com/drwl/annotaterb/issues/244)
+- classified\_sort and polymorphic associations [\#236](https://github.com/drwl/annotaterb/issues/236)
+- --show-migration also annotates the primary DB's schema version for models referencing the secondary DB [\#233](https://github.com/drwl/annotaterb/issues/233)
+- Annotations are not added on top of model files when columns'`comment:` contains Japanese characters in migrations [\#200](https://github.com/drwl/annotaterb/issues/200)
+- Feature: further customization to achieve more compact annotations [\#150](https://github.com/drwl/annotaterb/issues/150)
+- Version 5 change list [\#127](https://github.com/drwl/annotaterb/issues/127)
+- Reformat Column Comments [\#117](https://github.com/drwl/annotaterb/issues/117)
+
+**Merged pull requests:**
+
+- Bump version to v4.18.0 [\#246](https://github.com/drwl/annotaterb/pull/246) ([drwl](https://github.com/drwl))
+- Run on rollback in app with multiple databases [\#245](https://github.com/drwl/annotaterb/pull/245) ([z1lk](https://github.com/z1lk))
+- Speed up AnnotationDecider [\#243](https://github.com/drwl/annotaterb/pull/243) ([DRBragg](https://github.com/DRBragg))
+- Add AnnotateRb::Runner.running? method [\#242](https://github.com/drwl/annotaterb/pull/242) ([thewatts](https://github.com/thewatts))
+- fix: --show-migration to use per-model database connections [\#241](https://github.com/drwl/annotaterb/pull/241) ([OdenTakashi](https://github.com/OdenTakashi))
+- Fix: Support Japanese characters in column names [\#239](https://github.com/drwl/annotaterb/pull/239) ([tonystrawberry](https://github.com/tonystrawberry))
+- Fix classified\_sort to group polymorphic association columns together [\#238](https://github.com/drwl/annotaterb/pull/238) ([garriguv](https://github.com/garriguv))
+- Generate changelog for v4.17.0 [\#235](https://github.com/drwl/annotaterb/pull/235) ([drwl](https://github.com/drwl))
+
 ## [v4.17.0](https://github.com/drwl/annotaterb/tree/v4.17.0) (2025-07-14)
 
 [Full Changelog](https://github.com/drwl/annotaterb/compare/v4.16.0...v4.17.0)

data/README.md

@@ -146,10 +146,10 @@ Annotate model options:
         --ignore-unknown-models      don't display warnings for bad model files
     -I, --ignore-columns REGEX       don't annotate columns that match a given REGEX (i.e., `annotate -I '^(id|updated_at|created_at)'`
         --with-comment               include database comments in model annotations
-        --without-comment            include database comments in model annotations
+        --without-comment            exclude database comments in model annotations
         --with-column-comments       include column comments in model annotations
         --without-column-comments    exclude column comments in model annotations
-        --position-of-column-comments VALUE
+        --position-of-column-comment [with_name|rightmost_column]
                                      set the position, in the annotation block, of the column comment
         --with-table-comments        include table comments in model annotations
         --without-table-comments     exclude table comments in model annotations

data/VERSION

@@ -1 +1 @@
-4.18.0
+4.20.0

data/lib/annotate_rb/config_generator.rb

@@ -13,6 +13,9 @@ module AnnotateRb
         differences = defaults.keys - user_defaults.keys
         result = defaults.slice(*differences)
 
+        # Return empty string if no differences to avoid appending empty hash
+        return "" if result.empty?
+
         # Generates proper YAML including the leading hyphens `---` header
         yml_content = YAML.dump(result, StringIO.new).string
         # Remove the header

data/lib/annotate_rb/eager_loader.rb

@@ -7,17 +7,16 @@ module AnnotateRb
       def call(options)
         options[:require].count > 0 && options[:require].each { |path| require path }
 
-        if defined?(::Rails::Application)
-          if defined?(::Zeitwerk)
-            # Delegate to Zeitwerk to load stuff as needed
-          else
-            klass = ::Rails::Application.send(:subclasses).first
-            klass.eager_load!
-          end
+        if defined?(::Zeitwerk)
+          # Delegate to Zeitwerk to load stuff as needed
+          #   (Supports both Rails and non-Rails applications)
+        elsif defined?(::Rails::Application)
+          klass = ::Rails::Application.send(:subclasses).first
+          klass.eager_load!
         else
           model_files = ModelAnnotator::ModelFilesGetter.call(options)
           model_files&.each do |model_file|
-            require model_file
+            require File.join(*model_file)
           end
         end
       end

data/lib/annotate_rb/model_annotator/annotation/annotation_builder.rb

@@ -5,7 +5,7 @@ module AnnotateRb
     module Annotation
       class AnnotationBuilder
         class Annotation < Components::Base
-          attr_reader :version, :table_name, :table_comment, :max_size
+          attr_reader :version, :table_name, :table_comment, :max_size, :database_name
 
           def initialize(options, **input)
             @options = options
@@ -15,12 +15,13 @@ module AnnotateRb
             @table_comment = input[:table_comment]
             @max_size = input[:max_size]
             @model = input[:model]
+            @database_name = input[:database_name]
           end
 
           def body
             [
               MainHeader.new(version, @options[:include_version]),
-              SchemaHeader.new(table_name, table_comment, @options),
+              SchemaHeader.new(table_name, table_comment, database_name, @options),
               MarkdownHeader.new(max_size),
               *columns,
               IndexAnnotation::AnnotationBuilder.new(@model, @options).build,
@@ -59,38 +60,25 @@ module AnnotateRb
         end
 
         def build
-          version = migration_version_for_model(@model)
+          version = @model.migration_version
           table_name = @model.table_name
           table_comment = @model.connection.try(:table_comment, @model.table_name)
           max_size = @model.max_schema_info_width
+          database_name = @model.database_name if multi_db_environment?
 
           _annotation = Annotation.new(@options,
             version: version, table_name: table_name, table_comment: table_comment,
-            max_size: max_size, model: @model).build
+            max_size: max_size, model: @model, database_name: database_name).build
         end
 
         private
 
-        def migration_version_for_model(model)
-          return 0 unless @options[:include_version]
-
-          # Multi-database support: Cache migration versions per database connection to handle
-          # different schema versions across primary/secondary databases correctly.
-          # Example: primary → "current_version_primary", secondary → "current_version_secondary"
-          connection_pool_name = model.connection.pool.db_config.name
-          cache_key = "current_version_#{connection_pool_name}".to_sym
-
-          if @options.get_state(cache_key).nil?
-            migration_version = begin
-              model.connection.migration_context.current_version
-            rescue
-              0
-            end
-
-            @options.set_state(cache_key, migration_version)
+        def multi_db_environment?
+          if defined?(::Rails) && ::Rails.env
+            ActiveRecord::Base.configurations.configs_for(env_name: ::Rails.env).size > 1
+          else
+            false
           end
-
-          @options.get_state(cache_key)
         end
       end
     end

data/lib/annotate_rb/model_annotator/annotation/schema_header.rb

@@ -20,11 +20,28 @@ module AnnotateRb
           end
         end
 
-        attr_reader :table_name, :table_comment
+        class DatabaseName < Components::Base
+          attr_reader :name
+
+          def initialize(name)
+            @name = name
+          end
+
+          def to_default
+            "# Database name: #{name}"
+          end
+
+          def to_markdown
+            "# Database name: `#{name}`"
+          end
+        end
+
+        attr_reader :table_name, :table_comment, :database_name
 
-        def initialize(table_name, table_comment, options)
+        def initialize(table_name, table_comment, database_name, options)
           @table_name = table_name
           @table_comment = table_comment
+          @database_name = database_name
           @options = options
         end
 
@@ -32,8 +49,9 @@ module AnnotateRb
           [
             Components::BlankCommentLine.new,
             TableName.new(name),
+            (DatabaseName.new(database_name) if database_name),
             Components::BlankCommentLine.new
-          ]
+          ].compact
         end
 
         def to_default

data/lib/annotate_rb/model_annotator/annotation_decider.rb

@@ -16,17 +16,26 @@ module AnnotateRb
 
         begin
           klass = ModelClassGetter.call(@file, @options)
-          return false unless klass.respond_to?(:descends_from_active_record?) && klass.descends_from_active_record? && klass.table_exists?
 
-          return @options[:exclude_sti_subclasses] ? klass.base_class? : true
+          return false unless klass.respond_to?(:descends_from_active_record?)
+
+          # Skip annotating STI classes
+          if @options[:exclude_sti_subclasses] && !klass.descends_from_active_record?
+            return false
+          end
+
+          return false if klass.abstract_class?
+          return false unless klass.table_exists?
+
+          return true
         rescue BadModelFileError => e
           unless @options[:ignore_unknown_models]
             warn "Unable to process #{@file}: #{e.message}"
-            warn "\t" + e.backtrace.join("\n\t") if @options[:trace]
+            warn "\t#{e.backtrace.join("\n\t")}" if @options[:trace]
           end
         rescue => e
           warn "Unable to process #{@file}: #{e.message}"
-          warn "\t" + e.backtrace.join("\n\t") if @options[:trace]
+          warn "\t#{e.backtrace.join("\n\t")}" if @options[:trace]
         end
 
         false

data/lib/annotate_rb/model_annotator/column_annotation/column_component.rb

@@ -22,12 +22,16 @@ module AnnotateRb
         def name
           case position_of_column_comment
           when :with_name
-            "#{column.name}(#{column.comment.gsub(/\n/, '\\n')})"
+            "#{column.name}(#{escaped_column_comment})"
           else
             column.name
           end
         end
 
+        def escaped_column_comment
+          column.comment.to_s.gsub(/\n/, '\\n')
+        end
+
         def to_rdoc
           # standard:disable Lint/FormatParameterMismatch
           format("# %-#{max_name_size}.#{max_name_size}s<tt>%s</tt>",
@@ -56,7 +60,7 @@ module AnnotateRb
           name_remainder = max_name_size - name.length - non_ascii_length(name)
           type_remainder = (MD_TYPE_ALLOWANCE - 2) - type.length
           attributes_remainder = max_attributes_size + 1 - joined_attributes.length
-          comment_rightmost = (position_of_column_comment != :rightmost_column) ? "" : " | `#{@column.comment}`"
+          comment_rightmost = (position_of_column_comment != :rightmost_column) ? "" : " | `#{escaped_column_comment}`"
 
           # standard:disable Lint/FormatParameterMismatch
           format(
@@ -72,7 +76,7 @@ module AnnotateRb
         end
 
         def to_default
-          comment_rightmost = (position_of_column_comment == :rightmost_column) ? @column.comment : ""
+          comment_rightmost = (position_of_column_comment == :rightmost_column) ? escaped_column_comment : ""
           joined_attributes = attributes.join(", ")
           format(
             "#  %s:%s %s %s",

data/lib/annotate_rb/model_annotator/model_files_getter.rb

@@ -32,9 +32,8 @@ module AnnotateRb
             warn "Either specify models on the command line, or use the --model-dir option."
             warn "Call 'annotaterb --help' for more info."
             # exit 1 # TODO: Return exit code back to caller. Right now it messes up RSpec being able to run
-          else
-            model_files
           end
+          model_files
         end
 
         private

data/lib/annotate_rb/model_annotator/model_wrapper.rb

@@ -38,6 +38,10 @@ module AnnotateRb
         @klass.connection
       end
 
+      def database_name
+        connection.pool.db_config.name
+      end
+
       # Returns the unmodified model columns
       def raw_columns
         @raw_columns ||= @klass.columns
@@ -221,6 +225,28 @@ module AnnotateRb
           @klass.name.foreign_key.to_sym
         ]
       end
+
+      def migration_version
+        return 0 unless @options[:include_version]
+
+        # Multi-database support: Cache migration versions per database connection to handle
+        # different schema versions across primary/secondary databases correctly.
+        # Example: primary → "current_version_primary", secondary → "current_version_secondary"
+        connection_pool_name = connection.pool.db_config.name
+        cache_key = "current_version_#{connection_pool_name}".to_sym
+
+        if @options.get_state(cache_key).nil?
+          migration_version = begin
+            connection.migration_context.current_version
+          rescue
+            0
+          end
+
+          @options.set_state(cache_key, migration_version)
+        end
+
+        @options.get_state(cache_key)
+      end
     end
   end
 end

data/lib/annotate_rb/parser.rb

@@ -246,9 +246,9 @@ module AnnotateRb
         @options[:with_column_comments] = false
       end
 
-      option_parser.on("--position-of-column-comments VALUE",
+      option_parser.on("--position-of-column-comment [with_name|rightmost_column]",
         "set the position, in the annotation block, of the column comment") do |value|
-        @options[:position_of_column_comments] = value.to_sym
+        @options[:position_of_column_comment] = value.to_sym
       end
 
       option_parser.on("--with-table-comments",
@@ -423,9 +423,9 @@ module AnnotateRb
       end
 
       option_parser.on("-e",
-        "--exclude [tests,fixtures,factories,serializers]",
+        "--exclude [tests,fixtures,factories,serializers,sti_subclasses]",
         Array,
-        "Do not annotate fixtures, test files, factories, and/or serializers") do |exclusions|
+        "Do not annotate fixtures, test files, factories, serializers, and/or sti subclasses") do |exclusions|
         exclusions ||= EXCLUSION_LIST
         exclusions.each { |exclusion| @options["exclude_#{exclusion}".to_sym] = true }
       end

data/lib/annotate_rb/route_annotator/base_processor.rb

@@ -26,6 +26,10 @@ module AnnotateRb
         if existing_text == new_text
           false
         else
+          if options[:frozen]
+            abort "AnnotateRb error. #{routes_file} needs to be updated, but annotaterb was run with `--frozen`."
+          end
+
           write(new_text)
           true
         end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: annotaterb
 version: !ruby/object:Gem::Version
-  version: 4.18.0
+  version: 4.20.0
 platform: ruby
 authors:
 - Andrew W. Lee
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-04 00:00:00.000000000 Z
+date: 2025-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord