annotaterb 4.15.0 → 4.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a31463c338bd23299c7249e3c444d8c1b630157bf9905cfeb203dfafb1a4d16a
-  data.tar.gz: ad12fccdeeb0186d6627ba237c417c637b1b6136f354313e81f09de90cef4665
+  metadata.gz: 8789a11055d7fe2e2631a4c8ca0b3e05e20e365c16a31a2ea21ba6c1f90eda60
+  data.tar.gz: cbd50d2e0be48c2ffc55c600b5e1a5d6ae5864224d04180924a473395c1543eb
 SHA512:
-  metadata.gz: af6ec6a16d36b65b00eb28f4736c46682aa0d47da4869503eaecb8a58a8ff34f783ac3986c09200f125279666a8b30658af1ba91a9ad5829d789846c1c9e82dd
-  data.tar.gz: ad7fbd08360072a24c2fbea2808c180806ae89da5775689d1f7cc2824fead770b771ac41667056e68da0921ae13948a6f3da48883ab2f0328506cbf7158a63c0
+  metadata.gz: a51864d58bb429fd7166c16c98e179c926b5d2cf06b294f7b476f36e6dce5662d5f3ea20881ef0ac773535f3ccd3ddf4e26d35d833ba813bbc955a38191a2ea5
+  data.tar.gz: 78349c0ac08e212a9c6c0d40315d4bb18eba61e0dea77a580c133b76235a04cd3e78072c6d85814d3081de3e7c53eaa19e7297f9148e3c45bfe8567cbe7ce559

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [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)
+
+**Implemented enhancements:**
+
+- Feature Request: Add Option to Place Annotations Above Nested Classes or Modules. [\#186](https://github.com/drwl/annotaterb/issues/186)
+
+**Closed issues:**
+
+- Misleading pattern examples in documentation for `additional_file_patterns` [\#221](https://github.com/drwl/annotaterb/issues/221)
+- Permission denied for table pg\_index [\#209](https://github.com/drwl/annotaterb/issues/209)
+- Performance regression relative to pre-fork? [\#205](https://github.com/drwl/annotaterb/issues/205)
+- Add back ruby configuration option? [\#203](https://github.com/drwl/annotaterb/issues/203)
+- Enable frozen mode when CI environment variable is set [\#171](https://github.com/drwl/annotaterb/issues/171)
+
+**Merged pull requests:**
+
+-  Bump version to v4.16.0 [\#228](https://github.com/drwl/annotaterb/pull/228) ([drwl](https://github.com/drwl))
+- chore: add --with-column-comments readme documentation [\#227](https://github.com/drwl/annotaterb/pull/227) ([jonmcelroy-appfolio](https://github.com/jonmcelroy-appfolio))
+- Drop Ruby 2.7 support and improve CI [\#226](https://github.com/drwl/annotaterb/pull/226) ([drwl](https://github.com/drwl))
+- Pass .annotaterb.yml through ERB [\#225](https://github.com/drwl/annotaterb/pull/225) ([fxn](https://github.com/fxn))
+- feat: Add `--nested-position` option for placing annotations above nested classes. [\#223](https://github.com/drwl/annotaterb/pull/223) ([yamat47](https://github.com/yamat47))
+- Fix for: Misleading pattern examples in documentation for additional\_file\_patterns [\#222](https://github.com/drwl/annotaterb/pull/222) ([skliarov](https://github.com/skliarov))
+- Move activerecord dependency into gemspec [\#220](https://github.com/drwl/annotaterb/pull/220) ([drwl](https://github.com/drwl))
+- Generate changelog for v4.15.0 [\#219](https://github.com/drwl/annotaterb/pull/219) ([drwl](https://github.com/drwl))
+- chore: add rake task to automatically deploy to rubygems [\#183](https://github.com/drwl/annotaterb/pull/183) ([OdenTakashi](https://github.com/OdenTakashi))
+
+## [v4.15.0](https://github.com/drwl/annotaterb/tree/v4.15.0) (2025-05-30)
+
+[Full Changelog](https://github.com/drwl/annotaterb/compare/v4.14.1...v4.15.0)
+
+**Closed issues:**
+
+- Feature request: packs-rails support [\#99](https://github.com/drwl/annotaterb/issues/99)
+- Annotate models using Zeitwerk namespaces [\#82](https://github.com/drwl/annotaterb/issues/82)
+
+**Merged pull requests:**
+
+- Bump version to v4.15.0 [\#218](https://github.com/drwl/annotaterb/pull/218) ([drwl](https://github.com/drwl))
+- Add debug logs for model annotation [\#217](https://github.com/drwl/annotaterb/pull/217) ([jarredhawkins](https://github.com/jarredhawkins))
+- Cache retrieved indexes in ModelWrapper [\#215](https://github.com/drwl/annotaterb/pull/215) ([tr4b4nt](https://github.com/tr4b4nt))
+- feat: identify unique indexes in simple\_indexes option [\#214](https://github.com/drwl/annotaterb/pull/214) ([amerritt14](https://github.com/amerritt14))
+- fix: Handle case when table\_name\_prefix specified as symbol [\#208](https://github.com/drwl/annotaterb/pull/208) ([gururuby](https://github.com/gururuby))
+- Support the glob pattern in `root_dir` and `model_dir` [\#198](https://github.com/drwl/annotaterb/pull/198) ([sinsoku](https://github.com/sinsoku))
+- Fix `changelog_uri` in gemspec [\#192](https://github.com/drwl/annotaterb/pull/192) ([y-yagi](https://github.com/y-yagi))
+- Generate changelog for v4.14.0 [\#191](https://github.com/drwl/annotaterb/pull/191) ([drwl](https://github.com/drwl))
+- feat: add `timestamp_columns` config option [\#173](https://github.com/drwl/annotaterb/pull/173) ([pbernays](https://github.com/pbernays))
+
+## [v4.14.1](https://github.com/drwl/annotaterb/tree/v4.14.1) (2025-03-31)
+
+[Full Changelog](https://github.com/drwl/annotaterb/compare/v4.14.0...v4.14.1)
+
+**Closed issues:**
+
+- Sort by database order [\#194](https://github.com/drwl/annotaterb/issues/194)
+- “wrong number of arguments \(given 0, expected 1..2\)” when using enum in a Rails 8 model [\#184](https://github.com/drwl/annotaterb/issues/184)
+
 ## [v4.14.0](https://github.com/drwl/annotaterb/tree/v4.14.0) (2025-02-17)
 
 [Full Changelog](https://github.com/drwl/annotaterb/compare/v4.13.0...v4.14.0)

data/README.md

@@ -134,6 +134,7 @@ 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 
 
 Annotate routes options:
     Usage: annotaterb routes [options]
@@ -149,7 +150,7 @@ Command options:
 Additional options that work for annotating models and routes
 
         --additional-file-patterns path1,path2,path3
-                                     Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)
+                                     Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%MODEL_NAME%/*.rb,/baz/%MODEL_NAME%.rb`)
     -d, --delete                     Remove annotations from all model files or the routes.rb file
         --model-dir dir              Annotate model files stored in dir rather than app/models, separate multiple dirs with commas
         --root-dir dir               Annotate files stored within root dir projects, separate multiple dirs with commas
@@ -192,7 +193,7 @@ Previously in the [Annotate](https://github.com/ctran/annotate_models) you could
 position: after
 ```
 
-Annotaterb reads first from the configuration file, if it exists, then merges it with any options passed into the CLI. 
+Annotaterb reads first the configuration file, if it exists, passes its content through ERB, and merges the result with any options passed into the CLI.
 
 For further details visit the [section in the migration guide](MIGRATION_GUIDE.md#automatic-annotations-after-running-database-migration-commands).
 

data/VERSION

@@ -1 +1 @@
-4.15.0
+4.17.0

data/lib/annotate_rb/config_loader.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "erb"
+
 module AnnotateRb
   # Raised when a configuration file is not found.
   class ConfigNotFoundError < StandardError
@@ -20,8 +22,9 @@ module AnnotateRb
       # Method from Rubocop::ConfigLoader
       def load_yaml_configuration(absolute_path)
         file_contents = read_file(absolute_path)
+        yaml_code = ERB.new(file_contents).result
 
-        hash = yaml_safe_load(file_contents, absolute_path) || {}
+        hash = yaml_safe_load(yaml_code, absolute_path) || {}
 
         # TODO: Print config if debug flag/option is set
 

data/lib/annotate_rb/model_annotator/annotated_file/generator.rb

@@ -47,22 +47,63 @@ module AnnotateRb
         def content_annotated_before(parsed, content_without_annotations, write_position)
           same_write_position = @parsed_file.has_annotations? && @parsed_file.annotation_position.to_s == write_position
 
-          # Could error if there's no class or module declaration
-          _constant_name, line_number_before = parsed.starts.first
+          _constant_name, line_number_before = determine_annotation_position(parsed)
 
           content_with_annotations_written_before = []
           content_with_annotations_written_before << content_without_annotations.lines[0...line_number_before]
           content_with_annotations_written_before << $/ if @parsed_file.has_leading_whitespace? && same_write_position
-          content_with_annotations_written_before << @new_wrapped_annotations.lines
+          content_with_annotations_written_before << formatted_annotations(content_without_annotations, line_number_before)
           content_with_annotations_written_before << $/ if @parsed_file.has_trailing_whitespace? && same_write_position
           content_with_annotations_written_before << content_without_annotations.lines[line_number_before..]
 
           content_with_annotations_written_before.join
         end
 
+        # Determines where to place the annotation based on the nested_position option.
+        # When nested_position is enabled, finds the most deeply nested class declaration
+        # to place annotations directly above nested classes instead of at the file top.
+        def determine_annotation_position(parsed)
+          # Handle empty files where no classes/modules are found
+          return [nil, 0] if parsed.starts.empty?
+
+          return parsed.starts.first unless @options[:nested_position]
+
+          class_entries = parsed.starts.select { |name, _line| parsed.type_map[name] == :class }
+          class_entries.last || parsed.starts.first
+        end
+
+        # Formats annotations with appropriate indentation for consistent code structure.
+        # Applies the same indentation level as the target line to maintain proper
+        # code alignment when using nested positioning.
+        def formatted_annotations(content_without_annotations, line_number_before)
+          indentation = determine_indentation(content_without_annotations, line_number_before)
+          @new_wrapped_annotations.lines.map { |line| "#{indentation}#{line}" }
+        end
+
+        # Calculates the indentation string to apply to annotations for nested positioning.
+        # Extracts leading whitespace from the target line to preserve visual hierarchy
+        # and readability of nested code structures.
+        def determine_indentation(content_without_annotations, line_number_before)
+          return "" unless @options[:nested_position] && line_number_before > 0
+
+          target_line = content_without_annotations.lines[line_number_before]
+          target_line&.match(/^(\s*)/)&.[](1) || ""
+        end
+
         def content_annotated_after(parsed, content_without_annotations)
           _constant_name, line_number_after = parsed.ends.last
 
+          # Handle empty files where no classes/modules are found
+          if line_number_after.nil?
+            content_lines = content_without_annotations.lines
+            # For empty files, append annotations at the end
+            content_with_annotations_written_after = []
+            content_with_annotations_written_after << content_lines
+            content_with_annotations_written_after << $/ unless content_lines.empty?
+            content_with_annotations_written_after << @new_wrapped_annotations.lines
+            return content_with_annotations_written_after.join
+          end
+
           content_with_annotations_written_after = []
           content_with_annotations_written_after << content_without_annotations.lines[0..line_number_after]
           content_with_annotations_written_after << $/

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

@@ -12,42 +12,23 @@ module AnnotateRb
         end
 
         def build
-          is_primary_key = is_column_primary_key?(@model, @column.name)
-
-          table_indices = @model.retrieve_indexes_from_table
-          column_indices = table_indices.select { |ind| ind.columns.include?(@column.name) }
-          column_defaults = @model.column_defaults
-
-          column_attributes = AttributesBuilder.new(@column, @options, is_primary_key, column_indices, column_defaults).build
-          formatted_column_type = TypeBuilder.new(@column, @options, column_defaults).build
+          column_attributes = @model.built_attributes[@column.name]
+          formatted_column_type = TypeBuilder.new(@column, @options, @model.column_defaults).build
 
           display_column_comments = @options[:with_comment] && @options[:with_column_comments]
-          col_name = if display_column_comments && @model.with_comments? && @column.comment
-            "#{@column.name}(#{@column.comment.gsub(/\n/, '\\n')})"
-          else
-            @column.name
-          end
-
-          _component = ColumnComponent.new(col_name, @max_size, formatted_column_type, column_attributes)
-        end
-
-        private
-
-        # TODO: Simplify this conditional
-        def is_column_primary_key?(model, column_name)
-          if model.primary_key
-            if model.primary_key.is_a?(Array)
-              # If the model has multiple primary keys, check if this column is one of them
-              if model.primary_key.collect(&:to_sym).include?(column_name.to_sym)
-                return true
-              end
-            elsif column_name.to_sym == model.primary_key.to_sym
-              # If model has 1 primary key, check if this column is it
-              return true
-            end
-          end
-
-          false
+          display_column_comments &&= @model.with_comments? && @column.comment
+          position_of_column_comment = @options[:position_of_column_comment] || Options::FLAG_OPTIONS[:position_of_column_comment] if display_column_comments
+
+          max_attributes_size = @model.built_attributes.values.map { |v| v.join(", ").length }.max
+
+          _component = ColumnComponent.new(
+            column: @column,
+            max_name_size: @max_size,
+            type: formatted_column_type,
+            attributes: column_attributes,
+            position_of_column_comment: position_of_column_comment,
+            max_attributes_size: max_attributes_size
+          )
         end
       end
     end

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

@@ -6,19 +6,31 @@ module AnnotateRb
       class ColumnComponent < Components::Base
         MD_TYPE_ALLOWANCE = 18
         BARE_TYPE_ALLOWANCE = 16
+        MIN_SPACES_BEFORE_COMMENT = 4
 
-        attr_reader :name, :max_size, :type, :attributes
+        attr_reader :column, :max_name_size, :type, :attributes, :position_of_column_comment, :max_attributes_size
 
-        def initialize(name, max_size, type, attributes)
-          @name = name
-          @max_size = max_size
+        def initialize(column:, max_name_size:, type:, attributes:, position_of_column_comment:, max_attributes_size:)
+          @column = column
+          @max_name_size = max_name_size
           @type = type
           @attributes = attributes
+          @position_of_column_comment = position_of_column_comment
+          @max_attributes_size = max_attributes_size
+        end
+
+        def name
+          case position_of_column_comment
+          when :with_name
+            "#{column.name}(#{column.comment.gsub(/\n/, '\\n')})"
+          else
+            column.name
+          end
         end
 
         def to_rdoc
           # standard:disable Lint/FormatParameterMismatch
-          format("# %-#{max_size}.#{max_size}s<tt>%s</tt>",
+          format("# %-#{max_name_size}.#{max_name_size}s<tt>%s</tt>",
             "*#{name}*::",
             attributes.unshift(type).join(", ")).rstrip
           # standard:enable Lint/FormatParameterMismatch
@@ -40,24 +52,35 @@ module AnnotateRb
         end
 
         def to_markdown
-          name_remainder = max_size - name.length - non_ascii_length(name)
+          joined_attributes = attributes.join(", ").rstrip
+          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}`"
 
           # standard:disable Lint/FormatParameterMismatch
-          format("# **`%s`**%#{name_remainder}s | `%s`%#{type_remainder}s | `%s`",
+          format(
+            "# **`%s`**%#{name_remainder}s | `%s`%#{type_remainder}s | `%s`%#{attributes_remainder}s", # %s",
             name,
             " ",
             type,
             " ",
-            attributes.join(", ").rstrip).gsub("``", "  ").rstrip
+            joined_attributes,
+            comment_rightmost.to_s
+          ).gsub("``", "  ").rstrip
           # standard:enable Lint/FormatParameterMismatch
         end
 
         def to_default
-          format("#  %s:%s %s",
-            mb_chars_ljust(name, max_size),
+          comment_rightmost = (position_of_column_comment == :rightmost_column) ? @column.comment : ""
+          joined_attributes = attributes.join(", ")
+          format(
+            "#  %s:%s %s %s",
+            mb_chars_ljust(name, max_name_size),
             mb_chars_ljust(type, BARE_TYPE_ALLOWANCE),
-            attributes.join(", ")).rstrip
+            mb_chars_ljust(joined_attributes, max_attributes_size.to_i + MIN_SPACES_BEFORE_COMMENT),
+            comment_rightmost
+          ).rstrip
         end
 
         private

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

@@ -18,7 +18,7 @@ module AnnotateRb
           max_size = indexes.map { |index| index.name.size }.max + 1
 
           indexes = indexes.sort_by(&:name).map do |index|
-            IndexComponent.new(index, max_size)
+            IndexComponent.new(index, max_size, @options)
           end
 
           _annotation = Annotation.new(indexes)

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

@@ -4,11 +4,12 @@ module AnnotateRb
   module ModelAnnotator
     module IndexAnnotation
       class IndexComponent < Components::Base
-        attr_reader :index, :max_size
+        attr_reader :index, :max_size, :options
 
-        def initialize(index, max_size)
+        def initialize(index, max_size, options)
           @index = index
           @max_size = max_size
+          @options = options
         end
 
         def to_default
@@ -34,11 +35,22 @@ module AnnotateRb
             ""
           end
 
+          include_info = ""
+          if options[:show_indexes_include]
+            value = index.try(:include)
+            include_info = if value.present? && value.any?
+              " INCLUDE (#{value.join(",")})"
+            else
+              ""
+            end
+          end
+
           # standard:disable Lint/FormatParameterMismatch
           sprintf(
-            "#  %-#{max_size}.#{max_size}s %s%s%s%s%s",
+            "#  %-#{max_size}.#{max_size}s %s%s%s%s%s%s",
             index.name,
             "(#{columns_info.join(",")})",
+            include_info,
             unique_info,
             nulls_not_distinct_info,
             where_info,
@@ -70,8 +82,19 @@ module AnnotateRb
             ""
           end
 
+          include_info = ""
+          if options[:show_indexes_include]
+            value = index.try(:include)
+            include_info = if value.present? && value.any?
+              " _include_ (#{value.join(",")})"
+            else
+              ""
+            end
+          end
+
           details = sprintf(
-            "%s%s%s%s",
+            "%s%s%s%s%s",
+            include_info,
             unique_info,
             nulls_not_distinct_info,
             where_info,

data/lib/annotate_rb/model_annotator/model_wrapper.rb

@@ -23,7 +23,7 @@ module AnnotateRb
             ignore_columns = @options[:ignore_columns]
             if ignore_columns
               cols = cols.reject do |col|
-                col.name.match(/#{ignore_columns}/)
+                col.name.match?(/#{ignore_columns}/)
               end
             end
 
@@ -91,7 +91,8 @@ module AnnotateRb
           begin
             cols = columns
 
-            if with_comments?
+            position_of_column_comment = @options.with_default_fallback(:position_of_column_comment)
+            if with_comments? && position_of_column_comment == :with_name
               column_widths = cols.map do |column|
                 column.name.size + (column.comment ? Helper.width(column.comment) : 0)
               end
@@ -108,6 +109,35 @@ module AnnotateRb
           end
       end
 
+      # TODO: Simplify this conditional
+      def is_column_primary_key?(column_name)
+        if primary_key
+          if primary_key.is_a?(Array)
+            # If the model has multiple primary keys, check if this column is one of them
+            if primary_key.collect(&:to_sym).include?(column_name.to_sym)
+              return true
+            end
+          elsif column_name.to_sym == primary_key.to_sym
+            # If model has 1 primary key, check if this column is it
+            return true
+          end
+        end
+
+        false
+      end
+
+      def built_attributes
+        @built_attributes ||= begin
+          table_indices = retrieve_indexes_from_table
+          columns.map do |column|
+            is_primary_key = is_column_primary_key?(column.name)
+            column_indices = table_indices.select { |ind| ind.columns.include?(column.name) }
+            built = ColumnAnnotation::AttributesBuilder.new(column, @options, is_primary_key, column_indices, column_defaults).build
+            [column.name, built]
+          end.to_h
+        end
+      end
+
       def retrieve_indexes_from_table
         @indexes_from_table ||= _retrieve_indexes_from_table
       end
@@ -143,6 +173,10 @@ module AnnotateRb
           raw_columns.map(&:comment).any? { |comment| !comment.nil? }
       end
 
+      def position_of_column_comment
+        @position_of_column_comment ||= @options[:position_of_column_comment]
+      end
+
       def classified_sort(cols)
         rest_cols = []
         timestamps = []

data/lib/annotate_rb/model_annotator/project_annotator.rb

@@ -42,7 +42,11 @@ module AnnotateRb
         klass.reset_column_information
         annotation = Annotation::AnnotationBuilder.new(klass, @options).build
         model_name = klass.name.underscore
-        table_name = klass.table_name
+
+        # In multi-database configurations, it is possible for different models to have the same table name but live
+        #   in different databases. Here we are opting to use the table name to find related files only when the model
+        #   is using the primary connection.
+        table_name = klass.table_name if klass.connection_specification_name == ActiveRecord::Base.name
 
         model_instruction = SingleFileAnnotatorInstruction.new(file, annotation, :position_in_class, @options)
         instructions << model_instruction

data/lib/annotate_rb/options.rb

@@ -48,6 +48,7 @@ module AnnotateRb
       show_check_constraints: false, # ModelAnnotator
       show_foreign_keys: true, # ModelAnnotator
       show_indexes: true, # ModelAnnotator
+      show_indexes_include: false, # ModelAnnotator
       show_virtual_columns: false, # ModelAnnotator
       simple_indexes: false, # ModelAnnotator
       sort: false, # ModelAnnotator
@@ -55,7 +56,8 @@ module AnnotateRb
       trace: false, # ModelAnnotator, but is part of Core
       with_comment: true, # ModelAnnotator
       with_column_comments: nil, # ModelAnnotator
-      with_table_comments: nil # ModelAnnotator
+      with_table_comments: nil, # ModelAnnotator
+      position_of_column_comment: :with_name # ModelAnnotator
     }.freeze
 
     OTHER_OPTIONS = {
@@ -118,13 +120,15 @@ module AnnotateRb
       :show_complete_foreign_keys,
       :show_foreign_keys,
       :show_indexes,
+      :show_indexes_include,
       :simple_indexes,
       :sort,
       :timestamp,
       :trace,
       :with_comment,
       :with_column_comments,
-      :with_table_comments
+      :with_table_comments,
+      :position_of_column_comment
     ].freeze
 
     OTHER_OPTION_KEYS = [
@@ -205,10 +209,15 @@ module AnnotateRb
       # Set column and table comments to default to :with_comment, if not set
       @options[:with_column_comments] = @options[:with_comment] if @options[:with_column_comments].nil?
       @options[:with_table_comments] = @options[:with_comment] if @options[:with_table_comments].nil?
+      @options[:position_of_column_comment] = @options[:position_of_column_comment].to_sym
 
       self
     end
 
+    def with_default_fallback(key)
+      @options[key] || DEFAULT_OPTIONS[key]
+    end
+
     def set_state(key, value, overwrite = false)
       if @state.key?(key) && !overwrite
         val = @state[key]

data/lib/annotate_rb/parser.rb

@@ -246,6 +246,11 @@ module AnnotateRb
         @options[:with_column_comments] = false
       end
 
+      option_parser.on("--position-of-column-comments VALUE",
+        "set the position, in the annotation block, of the column comment") do |value|
+        @options[:position_of_column_comments] = value.to_sym
+      end
+
       option_parser.on("--with-table-comments",
         "include table comments in model annotations") do
         @options[:with_table_comments] = true
@@ -264,6 +269,11 @@ module AnnotateRb
           [klass]
         end
       end
+
+      option_parser.on("--nested-position",
+        "Place annotations directly above nested classes or modules instead of at the top of the file.") do
+        @options[:nested_position] = true
+      end
     end
 
     def add_route_options_to_parser(option_parser)
@@ -362,7 +372,7 @@ module AnnotateRb
 
       option_parser.on("--additional-file-patterns path1,path2,path3",
         Array,
-        "Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)") do |additional_file_patterns|
+        "Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%MODEL_NAME%/*.rb,/baz/%MODEL_NAME%.rb`)") do |additional_file_patterns|
         @options[:additional_file_patterns] = additional_file_patterns
       end
 

data/lib/annotate_rb/route_annotator/helper.rb

@@ -3,7 +3,7 @@
 module AnnotateRb
   module RouteAnnotator
     module Helper
-      MAGIC_COMMENT_MATCHER = /(^#\s*encoding:.*)|(^# coding:.*)|(^# -\*- coding:.*)|(^# -\*- encoding\s?:.*)|(^#\s*frozen_string_literal:.+)|(^# -\*- frozen_string_literal\s*:.+-\*-)/.freeze
+      MAGIC_COMMENT_MATCHER = /(^#\s*encoding:.*)|(^# coding:.*)|(^# -\*- coding:.*)|(^# -\*- encoding\s?:.*)|(^#\s*frozen_string_literal:.+)|(^# -\*- frozen_string_literal\s*:.+-\*-)/
 
       class << self
         def routes_file_exist?

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: annotaterb
 version: !ruby/object:Gem::Version
-  version: 4.15.0
+  version: 4.17.0
 platform: ruby
 authors:
 - Andrew W. Lee
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-30 00:00:00.000000000 Z
-dependencies: []
+date: 2025-07-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
 description: Annotates Rails/ActiveRecord Models, routes, fixtures, and others based
   on the database schema.
 email:
@@ -131,7 +159,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="