annotaterb 4.19.0 → 4.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0759110968217261a67bb8c519e55398ff9f43392e6cc4771bbebf5f97ce0395'
-  data.tar.gz: d179acc1d279901b547475d5ee87d46346d671e083ef233d2e65e1a7c8d3f277
+  metadata.gz: d35263cf60a69ceabf708e6da1acb1aa7dbb9994028b36726d813a00ef0ec7f0
+  data.tar.gz: f7286ebed8b6b2c2d2c5edb78dbeaa89dc6052619c8631a7d5b299e76c13bd0e
 SHA512:
-  metadata.gz: 8c0c8deaf4685925e3992f0adc33ecc2d92c49049eea38e44881d510b06128e031569ab242b80e160d534b369985a4eb9bb28612682d10c7a4e254f18030078e
-  data.tar.gz: 1f37df086f3c6afd475e684bdc8458fd3ffe70ff245f2dc6b14786cd889e3b2107269064344f79c27425f46e0f599b3a6d3d4e7662844523c7a22bd799c49fc5
+  metadata.gz: fcd554627a6f477ae5120a98afde43b89f08aa6411ea64e2feba73f752b34499172a8bee267b7cf68f1fcd729a921e90738a6047c7f939239063cc2b935f95f3
+  data.tar.gz: 17ac0370bef28e3275368c7a0f93a74e0863042676656878ea94b69416d2a84ec39214f6368f70ff9c2ad2b45f1714488cb57235a8950fdfef3aa5c2ce9f315f

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [v4.20.0](https://github.com/drwl/annotaterb/tree/v4.20.0) (2025-10-20)
+
+[Full Changelog](https://github.com/drwl/annotaterb/compare/v4.19.0...v4.20.0)
+
+**Merged pull requests:**
+
+- Bump version to v4.20.0 [\#278](https://github.com/drwl/annotaterb/pull/278) ([drwl](https://github.com/drwl))
+- Bump github/codeql-action from 3 to 4 [\#277](https://github.com/drwl/annotaterb/pull/277) ([dependabot[bot]](https://github.com/apps/dependabot))
+- fix: position-of-column-comment option [\#275](https://github.com/drwl/annotaterb/pull/275) ([JohnnyKei](https://github.com/JohnnyKei))
+- feat: Add database name to annotations in multi-DB environments [\#272](https://github.com/drwl/annotaterb/pull/272) ([OdenTakashi](https://github.com/OdenTakashi))
+- fix: resolve YAML syntax error in update\_config generator [\#269](https://github.com/drwl/annotaterb/pull/269) ([ivy](https://github.com/ivy))
+- Update README.md [\#268](https://github.com/drwl/annotaterb/pull/268) ([torgoton](https://github.com/torgoton))
+- Honor --frozen option in routes [\#265](https://github.com/drwl/annotaterb/pull/265) ([garriguv](https://github.com/garriguv))
+- refactor\(test\): Default to single-DB environment for tests [\#264](https://github.com/drwl/annotaterb/pull/264) ([OdenTakashi](https://github.com/OdenTakashi))
+- Escape column comment newlines when using "rightmost" value for position\_of\_column\_comment option [\#263](https://github.com/drwl/annotaterb/pull/263) ([rowanhogan](https://github.com/rowanhogan))
+- chore: introduce switchable DB environment for specs [\#262](https://github.com/drwl/annotaterb/pull/262) ([OdenTakashi](https://github.com/OdenTakashi))
+- Generate changelog for v4.19.0 [\#260](https://github.com/drwl/annotaterb/pull/260) ([drwl](https://github.com/drwl))
+- Bump actions/checkout from 4 to 5 [\#257](https://github.com/drwl/annotaterb/pull/257) ([dependabot[bot]](https://github.com/apps/dependabot))
+
+## [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)

data/README.md

@@ -75,7 +75,7 @@ $ ANNOTATERB_SKIP_ON_DB_TASKS=1 bin/rails db:migrate
 The following Rails generator commands get added.
 
 ```sh
-$ bin/rails generator --help
+$ bin/rails generate --help
 
 ...
 
@@ -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
@@ -183,6 +183,7 @@ Additional options that work for annotating models and routes
         --exclude                    Do not annotate fixtures, test files, factories, and/or serializers
     -f [bare|rdoc|yard|markdown],    Render Schema Information as plain/RDoc/Yard/Markdown
         --format
+        --config_path [path]         Path to configuration file (by default, .annotaterb.yml in the root of the project)
     -p [before|top|after|bottom],    Place the annotations at the top (before) or the bottom (after) of the model/test/fixture/factory/route/serializer file(s)
         --position
         --pc, --position-in-class [before|top|after|bottom]
@@ -211,6 +212,14 @@ Additional options that work for annotating models and routes
 
 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.
 
+### Configuration file location
+
+AnnotateRb also supports other configuration file locations, and are searched for in the following locations (in order of precedence):
+- `.annotaterb.yml`
+- `config/annotaterb.yml`
+- `.config/.annotaterb.yml`
+- `.config/annotaterb/config.yml`
+
 ```yml
 # .annotaterb.yml
 

data/VERSION

@@ -1 +1 @@
-4.19.0
+4.21.0

data/lib/annotate_rb/config_finder.rb

@@ -1,20 +1,29 @@
 # frozen_string_literal: true
 
+require "pathname"
+
 module AnnotateRb
   class ConfigFinder
     DOTFILE = ".annotaterb.yml"
 
     class << self
+      attr_accessor :config_path
+
       def find_project_root
         # We should expect this method to be called from a Rails project root and returning it
         # e.g. "/Users/drwl/personal/annotaterb/dummyapp"
-        Dir.pwd
+        Pathname.pwd
       end
 
       def find_project_dotfile
-        file_path = File.expand_path(DOTFILE, find_project_root)
+        return @config_path if @config_path && File.exist?(@config_path)
 
-        return file_path if File.exist?(file_path)
+        [
+          find_project_root.join(DOTFILE),
+          find_project_root.join("config", DOTFILE.delete_prefix(".")),
+          find_project_root.join(".config", DOTFILE),
+          find_project_root.join(".config", "annotaterb", "config.yml")
+        ].find(&:exist?)
       end
     end
   end

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/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,
@@ -63,10 +64,23 @@ module AnnotateRb
           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 multi_db_environment?
+          return false if @options[:ignore_multi_database_name]
+
+          if defined?(::Rails) && ::Rails.env
+            ActiveRecord::Base.configurations.configs_for(env_name: ::Rails.env).size > 1
+          else
+            false
+          end
         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/check_constraint_annotation/annotation.rb

@@ -23,6 +23,14 @@ module AnnotateRb
           body.map(&:to_markdown).join("\n")
         end
 
+        def to_rdoc
+          body.map(&:to_rdoc).join("\n")
+        end
+
+        def to_yard
+          body.map(&:to_yard).join("\n")
+        end
+
         def to_default
           body.map(&:to_default).join("\n")
         end

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/foreign_key_annotation/annotation.rb

@@ -23,6 +23,14 @@ module AnnotateRb
           body.map(&:to_markdown).join("\n")
         end
 
+        def to_rdoc
+          body.map(&:to_rdoc).join("\n")
+        end
+
+        def to_yard
+          body.map(&:to_yard).join("\n")
+        end
+
         def to_default
           body.map(&:to_default).join("\n")
         end

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

@@ -23,6 +23,14 @@ module AnnotateRb
           body.map(&:to_markdown).join("\n")
         end
 
+        def to_rdoc
+          body.map(&:to_rdoc).join("\n")
+        end
+
+        def to_yard
+          body.map(&:to_yard).join("\n")
+        end
+
         def to_default
           body.map(&:to_default).join("\n")
         end

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
@@ -228,8 +232,7 @@ module AnnotateRb
         # 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
+        cache_key = "current_version_#{database_name}".to_sym
 
         if @options.get_state(cache_key).nil?
           migration_version = begin

data/lib/annotate_rb/options.rb

@@ -76,6 +76,7 @@ module AnnotateRb
       timestamp_columns: ModelAnnotator::ModelWrapper::DEFAULT_TIMESTAMP_COLUMNS,
 
       ignore_columns: nil, # ModelAnnotator
+      ignore_multi_database_name: false, # ModelAnnotator
       ignore_routes: nil, # RouteAnnotator
       ignore_unknown_models: false, # ModelAnnotator
       models: true, # Core
@@ -143,6 +144,7 @@ module AnnotateRb
       :ignore_columns,
       :ignore_routes,
       :ignore_unknown_models,
+      :ignore_multi_database_name,
       :models,
       :routes,
       :skip_on_db_migrate,

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",
@@ -436,6 +436,11 @@ module AnnotateRb
         "Render Schema Information as plain/RDoc/Yard/Markdown") do |format_type|
         @options["format_#{format_type}".to_sym] = true
       end
+
+      option_parser.on("--config-path [path]",
+        "Path to configuration file (by default, .annotaterb.yml in the root of the project)") do |path|
+        @options[:config_path] = path
+      end
     end
   end
 end

data/lib/annotate_rb/rake_bootstrapper.rb

@@ -3,8 +3,9 @@
 module AnnotateRb
   class RakeBootstrapper
     class << self
-      def call(options)
+      def call
         require "rake"
+
         load "./Rakefile" if File.exist?("./Rakefile") && !Rake::Task.task_defined?(:environment)
 
         begin

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

data/lib/annotate_rb/runner.rb

@@ -23,23 +23,23 @@ module AnnotateRb
     end
 
     def run(args)
-      config_file_options = ConfigLoader.load_config
       parser = Parser.new(args, {})
 
       parsed_options = parser.parse
       remaining_args = parser.remaining_args
 
+      AnnotateRb::ConfigFinder.config_path = parsed_options[:config_path] if parsed_options[:config_path]
+      config_file_options = ConfigLoader.load_config
       options = config_file_options.merge(parsed_options)
 
       @options = Options.from(options, {working_args: remaining_args})
-      AnnotateRb::RakeBootstrapper.call(@options)
+      AnnotateRb::RakeBootstrapper.call
 
-      if @options[:command]
-        @options[:command].call(@options)
-      else
-        # TODO
-        raise "Didn't specify a command"
-      end
+      raise "Didn't specify a command" unless @options[:command]
+
+      @options[:command].call(@options)
+
+      # TODO
     end
   end
 end

data/lib/annotate_rb.rb

@@ -2,14 +2,11 @@
 
 require "active_record"
 require "active_support"
-
-# Helper.fallback depends on this being required because it adds #present? to nil
-require "active_support/core_ext/object/blank"
-require "active_support/core_ext/class/subclasses"
-require "active_support/core_ext/string/inflections"
-
 require "rake"
 
+module AnnotateRb
+end
+
 require_relative "annotate_rb/helper"
 require_relative "annotate_rb/core"
 require_relative "annotate_rb/commands"
@@ -23,6 +20,3 @@ require_relative "annotate_rb/rake_bootstrapper"
 require_relative "annotate_rb/config_finder"
 require_relative "annotate_rb/config_loader"
 require_relative "annotate_rb/config_generator"
-
-module AnnotateRb
-end

data/lib/annotaterb.rb

@@ -1,4 +1,4 @@
 # Gem names that follow naming convention work seamlessly. However, this gem is "annotaterb" where in code it is
 # AnnotateRb. Because of this, we need this file so that the rest of the library automatically gets required.
 
-require "annotate_rb"
+require_relative "annotate_rb"

data/lib/generators/annotate_rb/hook/templates/annotate_rb.rake

@@ -4,5 +4,7 @@
 if Rails.env.development? && ENV["ANNOTATERB_SKIP_ON_DB_TASKS"].nil?
   require "annotate_rb"
 
+  # Can modify the config path here if needed - by default, it's .annotaterb.yml in the root of the project
+  # AnnotateRb::ConfigFinder.config_path = ""
   AnnotateRb::Core.load_rake_tasks
 end

metadata

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