annotaterb 4.17.0 → 4.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8789a11055d7fe2e2631a4c8ca0b3e05e20e365c16a31a2ea21ba6c1f90eda60
-  data.tar.gz: cbd50d2e0be48c2ffc55c600b5e1a5d6ae5864224d04180924a473395c1543eb
+  metadata.gz: '0759110968217261a67bb8c519e55398ff9f43392e6cc4771bbebf5f97ce0395'
+  data.tar.gz: d179acc1d279901b547475d5ee87d46346d671e083ef233d2e65e1a7c8d3f277
 SHA512:
-  metadata.gz: a51864d58bb429fd7166c16c98e179c926b5d2cf06b294f7b476f36e6dce5662d5f3ea20881ef0ac773535f3ccd3ddf4e26d35d833ba813bbc955a38191a2ea5
-  data.tar.gz: 78349c0ac08e212a9c6c0d40315d4bb18eba61e0dea77a580c133b76235a04cd3e78072c6d85814d3081de3e7c53eaa19e7297f9148e3c45bfe8567cbe7ce559
+  metadata.gz: 8c0c8deaf4685925e3992f0adc33ecc2d92c49049eea38e44881d510b06128e031569ab242b80e160d534b369985a4eb9bb28612682d10c7a4e254f18030078e
+  data.tar.gz: 1f37df086f3c6afd475e684bdc8458fd3ffe70ff245f2dc6b14786cd889e3b2107269064344f79c27425f46e0f599b3a6d3d4e7662844523c7a22bd799c49fc5

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [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)
+
+**Implemented enhancements:**
+
+- Place column comments at the end of the line \(feature suggestion\) [\#164](https://github.com/drwl/annotaterb/issues/164)
+
+**Fixed bugs:**
+
+- Model annotation chokes on an empty file [\#182](https://github.com/drwl/annotaterb/issues/182)
+
+**Closed issues:**
+
+- uninitialized constant Zeitwerk::VERSION [\#216](https://github.com/drwl/annotaterb/issues/216)
+- Incorrect annotation of fixture files when different models share the same table name in different databases [\#206](https://github.com/drwl/annotaterb/issues/206)
+- Should active record and active support be in the gemspec? [\#197](https://github.com/drwl/annotaterb/issues/197)
+
+**Merged pull requests:**
+
+- Bump version to v4.17.0 [\#234](https://github.com/drwl/annotaterb/pull/234) ([drwl](https://github.com/drwl))
+- Fix NoMethodError when processing empty files [\#232](https://github.com/drwl/annotaterb/pull/232) ([tanukiti1987](https://github.com/tanukiti1987))
+- Refactor column ignore to use `match?` [\#231](https://github.com/drwl/annotaterb/pull/231) ([tagliala](https://github.com/tagliala))
+- Fix standard configuration [\#230](https://github.com/drwl/annotaterb/pull/230) ([tagliala](https://github.com/tagliala))
+- Generate changelog for v4.16.0 [\#229](https://github.com/drwl/annotaterb/pull/229) ([drwl](https://github.com/drwl))
+- show included columns in indexes [\#211](https://github.com/drwl/annotaterb/pull/211) ([pineman](https://github.com/pineman))
+- fix: use model name for file retrieval when not connected to the primary DB. [\#207](https://github.com/drwl/annotaterb/pull/207) ([OdenTakashi](https://github.com/OdenTakashi))
+- Place column comments at the end of the line [\#199](https://github.com/drwl/annotaterb/pull/199) ([Adeynack](https://github.com/Adeynack))
+
 ## [v4.16.0](https://github.com/drwl/annotaterb/tree/v4.16.0) (2025-06-18)
 
 [Full Changelog](https://github.com/drwl/annotaterb/compare/v4.15.0...v4.16.0)

data/README.md

@@ -1,9 +1,11 @@
 ## AnnotateRb
+
 ### forked from the [Annotate aka AnnotateModels gem](https://github.com/ctran/annotate_models)
 
 A Ruby Gem that adds annotations to your Rails models and route files.
 
-----------
+---
+
 [![CI](https://github.com/drwl/annotaterb/actions/workflows/ci.yml/badge.svg)](https://github.com/drwl/annotaterb/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/annotaterb.svg)](https://badge.fury.io/rb/annotaterb)
 
@@ -32,7 +34,9 @@ The schema comment looks like this:
 class Task < ApplicationRecord
   ...
 ```
-----------
+
+---
+
 ## Installation
 
 ```sh
@@ -46,11 +50,12 @@ group :development do
   ...
 
   gem "annotaterb"
-  
+
   ...
 ```
 
 ### Automatically annotate models
+
 For Rails projects, model files can get automatically annotated after migration tasks. To do this, run the following command:
 
 ```sh
@@ -66,6 +71,7 @@ $ ANNOTATERB_SKIP_ON_DB_TASKS=1 bin/rails db:migrate
 ```
 
 ### Added Rails generators
+
 The following Rails generator commands get added.
 
 ```sh
@@ -83,18 +89,23 @@ AnnotateRb:
 ```
 
 `bin/rails g annotate_rb:config`
+
 - Generates a new configuration file, `.annotaterb.yml`, using defaults from the gem.
 
 `bin/rails g annotate_rb:hook`
+
 - Installs the Rake file to automatically annotate Rails models on a database task (e.g. AnnotateRb will automatically run after running `bin/rails db:migrate`).
 
 `bin/rails g annotate_rb:install`
+
 - Runs the `config` and `hook` generator commands
 
 `bin/rails g annotate_rb:update_config`
+
 - Appends to `.annotaterb.yml` any configuration key-value pairs that are used by the Gem. This is useful when there's a drift between the config file values and the gem defaults (i.e. when new features get added).
 
 ## Migrating from the annotate gem
+
 Refer to the [migration guide](MIGRATION_GUIDE.md).
 
 ## Usage
@@ -103,7 +114,7 @@ AnnotateRb has a CLI that you can use to add or remove annotations.
 
 ```sh
 # To show the CLI options
-$ bundle exec annotaterb 
+$ bundle exec annotaterb
 
 Usage: annotaterb [command] [options]
 
@@ -127,6 +138,7 @@ Annotate model options:
                                      Complete foreign key names in the annotation
     -i, --show-indexes               List the table's database indexes in the annotation
     -s, --simple-indexes             Concat the column's related indexes in the annotation
+    -c, --show-check-constraints     List the table's check constraints in the annotation
         --hide-limit-column-types VALUES
                                      don't show limit for given column types, separated by commas (i.e., `integer,boolean,text`)
         --hide-default-column-types VALUES
@@ -134,7 +146,15 @@ 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
-        --with-column-comments       include column comments in model annotations 
+        --without-comment            include 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
+                                     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
+        --classes-default-to-s class Custom classes to be represented with `to_s`, may be used multiple times
+        --nested-position            Place annotations directly above nested classes or modules instead of at the top of the file.
 
 Annotate routes options:
     Usage: annotaterb routes [options]
@@ -157,6 +177,7 @@ Additional options that work for annotating models and routes
         --ignore-model-subdirects    Ignore subdirectories of the models directory
         --sort                       Sort columns alphabetically, rather than in creation order
         --classified-sort            Sort columns alphabetically, but first goes id, then the rest columns, then the timestamp columns and then the association columns
+        --grouped-polymorphic        Group polymorphic associations together in the annotation when using --classified-sort
     -R, --require path               Additional file to require before loading models, may be used multiple times
     -e [tests,fixtures,factories,serializers],
         --exclude                    Do not annotate fixtures, test files, factories, and/or serializers
@@ -176,6 +197,8 @@ Additional options that work for annotating models and routes
                                      Place the annotations at the top (before) or the bottom (after) of the routes.rb file
         --ps, --position-in-serializer [before|top|after|bottom]
                                      Place the annotations at the top (before) or the bottom (after) of the serializer files
+        --pa, --position-in-additional-file-patterns [before|top|after|bottom]
+                                     Place the annotations at the top (before) or the bottom (after) of files captured in additional file patterns
         --force                      Force new annotations even if there are no changes.
         --debug                      Prints the options and outputs messages to make it easier to debug.
         --frozen                     Do not allow to change annotations. Exits non-zero if there are going to be changes to files.
@@ -185,6 +208,7 @@ Additional options that work for annotating models and routes
 ## Configuration
 
 ### Storing default options
+
 Previously in the [Annotate](https://github.com/ctran/annotate_models) you could pass options through the CLI or store them as environment variables. Annotaterb removes dependency on the environment variables and instead can read values from a `.annotaterb.yml` file stored in the Rails project root.
 
 ```yml
@@ -198,6 +222,7 @@ Annotaterb reads first the configuration file, if it exists, passes its content
 For further details visit the [section in the migration guide](MIGRATION_GUIDE.md#automatic-annotations-after-running-database-migration-commands).
 
 ### How to skip annotating a particular model
+
 If you want to always skip annotations on a particular model, add this string
 anywhere in the file:
 
@@ -211,6 +236,10 @@ migrations were run).
 If you prefer to sort alphabetically so that the results of annotation are
 consistent regardless of what order migrations are executed in, use `--sort`.
 
+You can also sort columns by type, then alphabetically using `--classified-sort`
+and `--grouped-polymorphic`: first goes id, then the rest columns, then the
+timestamp columns and then the association columns.
+
 ## License
 
 Released under the same license as Ruby. No Support. No Warranty.

data/VERSION

@@ -1 +1 @@
-4.17.0
+4.19.0

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

@@ -59,17 +59,7 @@ module AnnotateRb
         end
 
         def build
-          if @options.get_state(:current_version).nil?
-            migration_version = begin
-              ActiveRecord::Migrator.current_version
-            rescue
-              0
-            end
-
-            @options.set_state(:current_version, migration_version)
-          end
-
-          version = @options.get_state(:current_version)
+          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

data/lib/annotate_rb/model_annotator/annotation_decider.rb

@@ -17,36 +17,25 @@ module AnnotateRb
         begin
           klass = ModelClassGetter.call(@file, @options)
 
-          klass_is_a_class = klass.is_a?(Class)
-          # Methods such as #superclass only exist on a class. Because of how the code is structured, `klass` could be a
-          #  module that does not support the #superclass method, so we want to return early.
-          return false if !klass_is_a_class
+          return false unless klass.respond_to?(:descends_from_active_record?)
 
-          klass_inherits_active_record_base = klass < ActiveRecord::Base
-          klass_is_not_abstract = klass.respond_to?(:abstract_class?) && !klass.abstract_class?
-          klass_table_exists = klass.respond_to?(:table_exists?) && klass.table_exists?
-
-          not_sure_this_conditional = (!@options[:exclude_sti_subclasses] || !(klass.superclass < ActiveRecord::Base && klass.table_name == klass.superclass.table_name))
-
-          annotate_conditions = [
-            klass_is_a_class,
-            klass_inherits_active_record_base,
-            not_sure_this_conditional,
-            klass_is_not_abstract,
-            klass_table_exists
-          ]
+          # Skip annotating STI classes
+          if @options[:exclude_sti_subclasses] && !klass.descends_from_active_record?
+            return false
+          end
 
-          to_annotate = annotate_conditions.all?
+          return false if klass.abstract_class?
+          return false unless klass.table_exists?
 
-          return to_annotate
+          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
@@ -55,9 +44,9 @@ module AnnotateRb
       private
 
       def file_contains_skip_annotation
-        file_string = File.exist?(@file) ? File.read(@file) : ""
+        return false unless File.exist?(@file)
 
-        /#{SKIP_ANNOTATION_PREFIX}.*/o.match?(file_string)
+        /#{SKIP_ANNOTATION_PREFIX}.*/o.match?(File.read(@file))
       end
     end
   end

data/lib/annotate_rb/model_annotator/annotation_diff_generator.rb

@@ -11,8 +11,7 @@ module AnnotateRb
       #   - "#  status(a/b/c)    :string           not null"
       #   - "#  created_at       :datetime         not null"
       #   - "#  updated_at       :datetime         not null"
-      COLUMN_PATTERN = /^#[\t ]+[\w*.`\[\]():]+(?:\(.*?\))?[\t ]+.+$/
-
+      COLUMN_PATTERN = /^#[\t ]+[[\p{L}\p{N}_]*.`\[\]():]+(?:\(.*?\))?[\t ]+.+$/
       class << self
         def call(file_content, annotation_block)
           new(file_content, annotation_block).generate

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

@@ -28,7 +28,7 @@ module AnnotateRb
             end
 
             cols = cols.sort_by(&:name) if @options[:sort]
-            cols = classified_sort(cols) if @options[:classified_sort]
+            cols = classified_sort(cols, @options[:grouped_polymorphic]) if @options[:classified_sort]
 
             cols
           end
@@ -177,7 +177,7 @@ module AnnotateRb
         @position_of_column_comment ||= @options[:position_of_column_comment]
       end
 
-      def classified_sort(cols)
+      def classified_sort(cols, grouped_polymorphic)
         rest_cols = []
         timestamps = []
         associations = []
@@ -186,6 +186,8 @@ module AnnotateRb
         # specs don't load defaults, so ensure we have defaults here
         timestamp_columns = @options[:timestamp_columns] || DEFAULT_TIMESTAMP_COLUMNS
 
+        col_names = cols.map(&:name)
+
         cols.each do |c|
           if c.name.eql?("id")
             id = c
@@ -193,6 +195,9 @@ module AnnotateRb
             timestamps << c
           elsif c.name[-3, 3].eql?("_id")
             associations << c
+          elsif c.name[-5, 5].eql?("_type") && col_names.include?(c.name.sub(/_type$/, "_id")) && grouped_polymorphic
+            # This is a polymorphic association's type column
+            associations << c
           else
             rest_cols << c
           end
@@ -216,6 +221,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/options.rb

@@ -41,6 +41,7 @@ module AnnotateRb
       format_rdoc: false, # ModelAnnotator
       format_yard: false, # ModelAnnotator
       frozen: false, # ModelAnnotator, but should be used by both
+      grouped_polymorphic: false, # ModelAnnotator
       ignore_model_sub_dir: false, # ModelAnnotator
       ignore_unknown_models: false, # ModelAnnotator
       include_version: false, # ModelAnnotator
@@ -113,6 +114,7 @@ module AnnotateRb
       :format_rdoc,
       :format_yard,
       :frozen,
+      :grouped_polymorphic,
       :ignore_model_sub_dir,
       :ignore_unknown_models,
       :include_version,

data/lib/annotate_rb/parser.rb

@@ -407,6 +407,11 @@ module AnnotateRb
         @options[:classified_sort] = true
       end
 
+      option_parser.on("--grouped-polymorphic",
+        "Group polymorphic associations together in the annotation when using --classified-sort") do
+        @options[:grouped_polymorphic] = true
+      end
+
       option_parser.on("-R",
         "--require path",
         "Additional file to require before loading models, may be used multiple times") do |path|
@@ -418,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/runner.rb

@@ -3,9 +3,23 @@
 module AnnotateRb
   class Runner
     class << self
+      attr_reader :runner
+
       def run(args)
-        new.run(args)
+        self.runner = new
+
+        runner.run(args)
+
+        self.runner = nil
       end
+
+      def running?
+        !!runner
+      end
+
+      private
+
+      attr_writer :runner
     end
 
     def run(args)

data/lib/annotate_rb/tasks/annotate_models_migrate.rake

@@ -18,7 +18,7 @@ if defined?(Rails::Application) && Rails.version.split(".").first.to_i >= 6
 
   # If there's multiple databases, this appends database specific rake tasks to `migration_tasks`
   ActiveRecord::Tasks::DatabaseTasks.for_each(databases) do |database_name|
-    migration_tasks.concat(%w[db:migrate db:migrate:up db:migrate:down].map { |task| "#{task}:#{database_name}" })
+    migration_tasks.concat(%w[db:migrate db:migrate:up db:migrate:down db:rollback].map { |task| "#{task}:#{database_name}" })
   end
 end
 

metadata

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