annotaterb 4.22.0 → 4.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2be17a236402d5406e2f4d1f68a567bf51de51f924f66591adf9460bfacabe18
-  data.tar.gz: 48743c136f9a195bb1dbaa564bd8047c16411394a991b4c86b57a70844d0e121
+  metadata.gz: 249172f3c37299ac55df233909754c48456b629d11517ce03c84fae62232677d
+  data.tar.gz: 9fa726c0abbb3bc7508257d24e7e0f0e4f9a79c94e255909b8bf7162a2f25d9f
 SHA512:
-  metadata.gz: a203a269dbcf4c42a082a2088c6c38d8c4b97c3bbf9ab760762e3149294fb38dc31799aea2f3ece425504782cd2027187bd161ccf4a9c006aaa7a9a791094311
-  data.tar.gz: 8cc55f09f193f5f428db97afc1270386a06eb8185773cfd339830e1ee8e49631a1f203cced676fdb2f4d7d5c0b690f5aadc9108f63d3de588c019d7585c0011b
+  metadata.gz: f695ccb014c329b7c897f1832c4bb053df9fbec718198d68466884585b17f17fbfb6805a053024a38133196f7d9934aaff56d89c83598160966b1fc4dcaaaa3c
+  data.tar.gz: 73994c40f74a0c793cd974cf1369b59403e3b3a49ce6c643b661f9dfdffb7425dcfbb96c98ba2a23c3347861fa4cd759be380613d92627cb4046956af249dea3

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [v4.22.0](https://github.com/drwl/annotaterb/tree/v4.22.0) (2026-02-12)
+
+[Full Changelog](https://github.com/drwl/annotaterb/compare/v4.21.0...v4.22.0)
+
+**Fixed bugs:**
+
+- Yardoc formatting for comments on database attributes [\#162](https://github.com/drwl/annotaterb/issues/162)
+
+**Closed issues:**
+
+- New `ignore_multi_database_name` option seems to be non-functional [\#303](https://github.com/drwl/annotaterb/issues/303)
+- Changing sort options does not change annotations [\#294](https://github.com/drwl/annotaterb/issues/294)
+- CLI script for annotaterb not installed or runnable [\#290](https://github.com/drwl/annotaterb/issues/290)
+- Feature: ruby-lsp addon [\#175](https://github.com/drwl/annotaterb/issues/175)
+- Mounting ActionCable leads to weird annotation [\#161](https://github.com/drwl/annotaterb/issues/161)
+
+**Merged pull requests:**
+
+- Bump version to v4.22.0 [\#310](https://github.com/drwl/annotaterb/pull/310) ([drwl](https://github.com/drwl))
+- Run CI on CRuby 4.0 [\#308](https://github.com/drwl/annotaterb/pull/308) ([viralpraxis](https://github.com/viralpraxis))
+- Generate changelog for v4.21.0 [\#307](https://github.com/drwl/annotaterb/pull/307) ([drwl](https://github.com/drwl))
+- fix NoMethodError when using nested\_position with fixture files [\#298](https://github.com/drwl/annotaterb/pull/298) ([OdenTakashi](https://github.com/OdenTakashi))
+- fix: Respect configured sort [\#295](https://github.com/drwl/annotaterb/pull/295) ([patrickarnett](https://github.com/patrickarnett)) **(Maintainer note: this could result in annotations shifting depending on configuration, please create an issue if it is a breaking change)**
+- Use `#lease_connection` if available [\#292](https://github.com/drwl/annotaterb/pull/292) ([viralpraxis](https://github.com/viralpraxis))
+- refactor: simplify primary key check logic \(no functional changes\) [\#285](https://github.com/drwl/annotaterb/pull/285) ([OdenTakashi](https://github.com/OdenTakashi))
+- Honor skip\_on\_db\_migrate config option when runnig migrate tasks [\#274](https://github.com/drwl/annotaterb/pull/274) ([martinechtner](https://github.com/martinechtner))
+
 ## [v4.21.0](https://github.com/drwl/annotaterb/tree/v4.21.0) (2026-01-30)
 
 [Full Changelog](https://github.com/drwl/annotaterb/compare/v4.20.0...v4.21.0)

data/README.md

@@ -64,6 +64,13 @@ $ bin/rails g annotate_rb:install
 
 This will copy a rake task into your Rails project's `lib/tasks` directory that will hook into the Rails project rake tasks, automatically running AnnotateRb after database migration rake tasks.
 
+```sh
+$ bin/rails db:migrate
+# ...
+# Annotating models
+# Annotated (1): app/models/task.rb
+```
+
 To skip the automatic annotation that happens after a db task, pass the environment variable `ANNOTATERB_SKIP_ON_DB_TASKS=1` before your command.
 
 ```sh
@@ -184,10 +191,10 @@ Additional options that work for annotating models and routes
     -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]
-                                     Place the annotations at the top (before) or the bottom (after) of the model file
+    -p [before|top|after|bottom|before_doc],
+        --position                   Place the annotations at the top (before), bottom (after), or above the class documentation (before_doc) of the model/test/fixture/factory/route/serializer file(s)
+        --pc, --position-in-class [before|top|after|bottom|before_doc]
+                                     Place the annotations at the top (before), bottom (after), or above the class documentation (before_doc) of the model file
         --pf, --position-in-factory [before|top|after|bottom]
                                      Place the annotations at the top (before) or the bottom (after) of any factory files
         --px, --position-in-fixture [before|top|after|bottom]
@@ -230,6 +237,35 @@ 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).
 
+### Preserving class documentation comments
+
+By default, when `position_in_class` is `before` (or `top`), AnnotateRb places the schema annotation immediately before the class declaration line. Any human-written documentation comment that was directly above the class is therefore pushed above the annotation.
+
+If you prefer to keep the documentation comment adjacent to the class, set `position_in_class` to `before_doc`. The schema annotation is then inserted above the documentation comment block, leaving the comment directly before the class.
+
+```ruby
+# Source file:
+# Doc about User
+class User < ApplicationRecord
+end
+
+# With position_in_class: before  (default)
+# Doc about User
+# == Schema Information
+# ...
+class User < ApplicationRecord
+end
+
+# With position_in_class: before_doc
+# == Schema Information
+# ...
+# Doc about User
+class User < ApplicationRecord
+end
+```
+
+A "documentation comment" is the contiguous comment block immediately above the class declaration, with no blank line between the comments and the class. Recognized magic comments (`encoding`, `frozen_string_literal`, `shareable_constant_value`, `warn_indent`, `typed`, `rbs_inline`, plus Emacs/Vim style modelines) are excluded so the annotation can still be inserted between magic comments and the class doc.
+
 ### How to skip annotating a particular model
 
 If you want to always skip annotations on a particular model, add this string

data/VERSION

@@ -1 +1 @@
-4.22.0
+4.23.0

data/lib/annotate_rb/helper.rb

@@ -2,15 +2,38 @@
 
 module AnnotateRb
   module Helper
+    # Unicode ranges that typically occupy 2 columns in monospace terminals.
+    # This is a simplified wcwidth implementation.
+    DOUBLE_WIDTH_RANGES = [
+      0x1100..0x115F,   # Hangul Jamo
+      0x2E80..0x303E,   # CJK Radicals, Kangxi, CJK Symbols
+      0x3040..0x4DBF,   # Hiragana, Katakana, Bopomofo, CJK Ext A
+      0x4E00..0x9FFF,   # CJK Unified Ideographs
+      0xAC00..0xD7AF,   # Hangul Syllables
+      0xF900..0xFAFF,   # CJK Compatibility Ideographs
+      0xFE30..0xFE6F,   # CJK Compatibility Forms
+      0xFF01..0xFF60,   # Fullwidth Forms
+      0xFFE0..0xFFE6,   # Fullwidth Signs
+      0x20000..0x2FA1F, # CJK Extensions B-F
+      0x30000..0x3134F  # CJK Extensions G-I
+    ].freeze
+
     class << self
       def width(string)
-        string.chars.inject(0) { |acc, elem| acc + ((elem.bytesize == 3) ? 2 : 1) }
+        string.each_char.sum { |char| double_width?(char) ? 2 : 1 }
       end
 
       # TODO: Find another implementation that doesn't depend on ActiveSupport
       def fallback(*args)
         args.compact.detect(&:present?)
       end
+
+      private
+
+      def double_width?(char)
+        cp = char.ord
+        DOUBLE_WIDTH_RANGES.any? { |range| range.cover?(cp) }
+      end
     end
   end
 end

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

@@ -5,7 +5,7 @@ module AnnotateRb
     module AnnotatedFile
       # Generates the file with fresh annotations
       class Generator
-        def initialize(file_content, new_annotations, annotation_position, parser_klass, parsed_file, options)
+        def initialize(file_content, new_annotations, annotation_position, parser_klass, parsed_file, options, model_class_name: nil)
           @annotation_position = annotation_position
           @options = options
 
@@ -16,6 +16,7 @@ module AnnotateRb
 
           @parser = parser_klass
           @parsed_file = parsed_file
+          @model_class_name = model_class_name
         end
 
         # @return [String] Returns the annotated file content to be written back to a file
@@ -35,7 +36,7 @@ module AnnotateRb
           # We need to get class start and class end depending on the position
           parsed = @parser.parse(content_without_annotations)
 
-          _content = if %w[after bottom].include?(annotation_write_position)
+          _content = if Parser::AFTER_POSITIONS.include?(annotation_write_position)
             content_annotated_after(parsed, content_without_annotations)
           else
             content_annotated_before(parsed, content_without_annotations, annotation_write_position)
@@ -45,10 +46,14 @@ module AnnotateRb
         private
 
         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
+          same_write_position = same_side?(write_position)
 
           _constant_name, line_number_before = determine_annotation_position(parsed)
 
+          if Parser::DOC_AWARE_POSITIONS.include?(write_position)
+            line_number_before = class_doc_start_line(content_without_annotations.lines, line_number_before)
+          end
+
           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
@@ -59,17 +64,34 @@ module AnnotateRb
           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?
+        def same_side?(write_position)
+          return false unless @parsed_file.has_annotations?
+
+          new_side = Parser::AFTER_POSITIONS.include?(write_position) ? :after : :before
+          @parsed_file.annotation_position == new_side
+        end
 
-          return parsed.starts.first unless @options[:nested_position] && parsed.respond_to?(:type_map)
+        # Magic comments are excluded so annotations slot between them and
+        # the class doc rather than being treated as part of the doc.
+        def class_doc_start_line(content_lines, line_number_before)
+          doc_start = line_number_before
+          cursor = line_number_before - 1
 
-          class_entries = parsed.starts.select { |name, _line| parsed.type_map[name] == :class }
-          class_entries.last || parsed.starts.first
+          while cursor >= 0
+            line = content_lines[cursor]
+            break if line.match?(/\A\s*\z/)
+            break unless line.match?(/\A\s*#/)
+            break if FileParser::MagicComment.match?(line)
+
+            doc_start = cursor
+            cursor -= 1
+          end
+
+          doc_start
+        end
+
+        def determine_annotation_position(parsed)
+          FileParser::AnnotationTarget.find(parsed, @options, model_class_name: @model_class_name) || [nil, 0]
         end
 
         # Formats annotations with appropriate indentation for consistent code structure.

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

@@ -18,13 +18,26 @@ module AnnotateRb
         def update
           return "" if !@parsed_file.has_annotations?
 
-          new_annotation = wrapped_content(@new_annotations)
+          new_annotation = indent(wrapped_content(@new_annotations), existing_indentation)
 
           _content = @file_content.sub(@parsed_file.annotations) { new_annotation }
         end
 
         private
 
+        # Returns the leading whitespace of the existing annotation block so
+        # nested-position annotations keep their indentation across re-runs.
+        def existing_indentation
+          first_line = @parsed_file.annotations.lines.first
+          first_line&.match(/\A([ \t]*)/)&.[](1) || ""
+        end
+
+        def indent(content, indentation)
+          return content if indentation.empty?
+
+          content.lines.map { |line| (line == "\n") ? line : "#{indentation}#{line}" }.join
+        end
+
         def wrapped_content(content)
           wrapper_open = if @options[:wrapper_open]
             "# #{@options[:wrapper_open]}\n"

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

@@ -27,6 +27,7 @@ module AnnotateRb
               IndexAnnotation::AnnotationBuilder.new(@model, @options).build,
               ForeignKeyAnnotation::AnnotationBuilder.new(@model, @options).build,
               CheckConstraintAnnotation::AnnotationBuilder.new(@model, @options).build,
+              EnumAnnotation::AnnotationBuilder.new(@model, @options).build,
               SchemaFooter.new
             ]
           end

data/lib/annotate_rb/model_annotator/annotation_decider.rb

@@ -33,6 +33,9 @@ module AnnotateRb
             warn "Unable to process #{@file}: #{e.message}"
             warn "\t#{e.backtrace.join("\n\t")}" if @options[:trace]
           end
+        rescue ActiveRecord::ConnectionNotEstablished,
+          ActiveRecord::NoDatabaseError => e
+          abort "AnnotateRb: Database connection error - #{e.message}"
         rescue => e
           warn "Unable to process #{@file}: #{e.message}"
           warn "\t#{e.backtrace.join("\n\t")}" if @options[:trace]

data/lib/annotate_rb/model_annotator/annotation_diff_generator.rb

@@ -4,14 +4,17 @@ module AnnotateRb
   module ModelAnnotator
     # Compares the current file content and new annotation block and generates the column annotation differences
     class AnnotationDiffGenerator
-      HEADER_PATTERN = /(^# Table name:.*?\n(#.*\r?\n)*\r?)/
+      # Leading whitespace is tolerated so that annotations placed inside a
+      # nested module/class (i.e. with --nested-position, or hand-aligned)
+      # still match.
+      HEADER_PATTERN = /(^[ \t]*# Table name:.*?\n([ \t]*#.*\r?\n)*\r?)/
       # Example matches:
       #   - "#  id              :uuid             not null, primary key"
       #   - "#  title(length 255) :string          not null"
       #   - "#  status(a/b/c)    :string           not null"
       #   - "#  created_at       :datetime         not null"
       #   - "#  updated_at       :datetime         not null"
-      COLUMN_PATTERN = /^#[\t ]+[[\p{L}\p{N}_]*.`\[\]():]+(?:\(.*?\))?[\t ]+.+$/
+      COLUMN_PATTERN = /^[ \t]*#[\t ]+[[\p{L}\p{N}_]*.`\[\]():]+(?:\(.*?\))?[\t ]+.+$/
       class << self
         def call(file_content, annotation_block)
           new(file_content, annotation_block).generate
@@ -30,14 +33,16 @@ module AnnotateRb
         current_annotations = @file_content.match(HEADER_PATTERN).to_s
         new_annotations = @annotation_block.match(HEADER_PATTERN).to_s
 
+        # Strip leading whitespace from each scanned column so that an
+        # indented existing block compares equal to a flush-left new block.
         current_annotation_columns = if current_annotations.present?
-          current_annotations.scan(COLUMN_PATTERN)
+          current_annotations.scan(COLUMN_PATTERN).map(&:lstrip)
         else
           []
         end
 
         new_annotation_columns = if new_annotations.present?
-          new_annotations.scan(COLUMN_PATTERN)
+          new_annotations.scan(COLUMN_PATTERN).map(&:lstrip)
         else
           []
         end

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

@@ -84,6 +84,13 @@ module AnnotateRb
             end
           end
 
+          if column_type == "enum" && @options[:show_enums]
+            enum_type_name = @column.sql_type
+            if enum_type_name.present? && enum_type_name != "enum"
+              attrs << "enum_type: #{enum_type_name}"
+            end
+          end
+
           # Check if the column is a virtual column and print the function
           if @options[:show_virtual_columns] && @column.virtual?
             # Any whitespace in the function gets reduced to a single space

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

@@ -42,7 +42,7 @@ module AnnotateRb
 
         def to_yard
           res = ""
-          res += sprintf("# @!attribute #{name}") + "\n"
+          res += "# @!attribute #{name}\n"
 
           ruby_class = if @column.respond_to?(:array) && @column.array
             "Array<#{map_col_type_to_ruby_classes(type)}>"
@@ -50,7 +50,7 @@ module AnnotateRb
             map_col_type_to_ruby_classes(type)
           end
 
-          res += sprintf("#   @return [#{ruby_class}]")
+          res += "#   @return [#{ruby_class}]"
 
           res
         end

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

@@ -26,6 +26,10 @@ module AnnotateRb
           @column.type
         end
 
+        def sql_type
+          @column.sql_type.to_s
+        end
+
         def column_type_string
           if (@column.respond_to?(:bigint?) && @column.bigint?) || /\Abigint\b/ =~ @column.sql_type
             "bigint"

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module EnumAnnotation
+      class Annotation
+        HEADER_TEXT = "Enums"
+
+        def initialize(enums)
+          @enums = enums
+        end
+
+        def body
+          [
+            Components::BlankCommentLine.new,
+            Components::Header.new(HEADER_TEXT),
+            Components::BlankCommentLine.new,
+            *@enums
+          ]
+        end
+
+        def to_markdown
+          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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module EnumAnnotation
+      class AnnotationBuilder
+        def initialize(model, options)
+          @model = model
+          @options = options
+        end
+
+        def build
+          return Components::NilComponent.new unless @options[:show_enums]
+
+          enum_types = @model.enum_types
+          return Components::NilComponent.new if enum_types.empty?
+
+          # Filter to only enum types used by this table's columns
+          table_enum_types = @model.columns.select { |col| col.type == :enum }
+            .map { |col| col.sql_type.to_s }
+            .uniq
+
+          relevant_enums = enum_types
+            .filter_map { |name, values| [name.to_s, values] if table_enum_types.include?(name.to_s) }
+          return Components::NilComponent.new if relevant_enums.empty?
+
+          max_size = relevant_enums.map { |name, _values| name.size }.max + 1
+
+          components = relevant_enums.sort_by { |name, _values| name }.map do |name, values|
+            EnumComponent.new(name, values, max_size)
+          end
+
+          Annotation.new(components)
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/enum_annotation/enum_component.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module EnumAnnotation
+      class EnumComponent < Components::Base
+        attr_reader :name, :values, :max_size
+
+        def initialize(name, values, max_size)
+          @name = name
+          @values = values
+          @max_size = max_size
+        end
+
+        def to_default
+          # standard:disable Lint/FormatParameterMismatch
+          sprintf("#  %-#{max_size}.#{max_size}s %s", name, values.join(", ")).rstrip
+          # standard:enable Lint/FormatParameterMismatch
+        end
+
+        def to_markdown
+          sprintf("# * `%s`: `%s`", name, values.join(", "))
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/enum_annotation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module EnumAnnotation
+      autoload :AnnotationBuilder, "annotate_rb/model_annotator/enum_annotation/annotation_builder"
+      autoload :Annotation, "annotate_rb/model_annotator/enum_annotation/annotation"
+      autoload :EnumComponent, "annotate_rb/model_annotator/enum_annotation/enum_component"
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/file_parser/annotation_finder.rb

@@ -8,6 +8,20 @@ module AnnotateRb
         COMPAT_PREFIX_MD = "## Schema Info"
         DEFAULT_ANNOTATION_ENDING = "#"
 
+        SCHEMA_HEADER_PREFIXES = [
+          COMPAT_PREFIX,
+          COMPAT_PREFIX_MD,
+          "Table name:",
+          "Database name:",
+          "Schema version:"
+        ].freeze
+
+        SCHEMA_HEADER_EXACT = [
+          IndexAnnotation::Annotation::HEADER_TEXT,
+          ForeignKeyAnnotation::Annotation::HEADER_TEXT,
+          CheckConstraintAnnotation::Annotation::HEADER_TEXT
+        ].freeze
+
         class MalformedAnnotation < StandardError; end
 
         class NoAnnotationFound < StandardError; end
@@ -70,10 +84,7 @@ module AnnotateRb
               end
             end
           else
-            # Walk back until we find the end of the annotation comment block
-            while ending > start && comments[ending].first != DEFAULT_ANNOTATION_ENDING
-              ending -= 1
-            end
+            ending = walk_forward_through_schema(comments, start, ending)
           end
 
           # We want .last because we want the line indexes
@@ -95,6 +106,30 @@ module AnnotateRb
         def annotated?
           @annotation_start && @annotation_end
         end
+
+        private
+
+        def walk_forward_through_schema(comments, start, block_end)
+          ending = start
+          while ending < block_end
+            break unless schema_like?(comments[ending + 1].first)
+            ending += 1
+          end
+          ending
+        end
+
+        # Tabular rows have ≥2 leading spaces after `#`; prose has at most one.
+        def schema_like?(comment)
+          return true if comment == DEFAULT_ANNOTATION_ENDING
+
+          text = comment.sub(/\A#\s?/, "")
+          return false if text.empty?
+
+          return true if SCHEMA_HEADER_PREFIXES.any? { |p| text.start_with?(p) }
+          return true if SCHEMA_HEADER_EXACT.include?(text)
+
+          comment.match?(/\A#\s{2,}\S/)
+        end
       end
     end
   end

data/lib/annotate_rb/model_annotator/file_parser/annotation_target.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module FileParser
+      # When `model_class_name` is given, matches that class declaration directly
+      # so inner classes inside the model body cannot be mistaken for the target.
+      module AnnotationTarget
+        SKIP_NAMES = %w[require require_relative load].freeze
+
+        def self.find(parser, options, model_class_name: nil)
+          starts = parser.starts.reject { |entry| SKIP_NAMES.include?(entry.first) }
+          return nil if starts.empty?
+
+          return starts.first unless options[:nested_position] && parser.respond_to?(:type_map)
+
+          if model_class_name && parser.type_map[model_class_name] == :class
+            match = starts.find { |name, _line| name == model_class_name }
+            return match if match
+          end
+
+          class_entries = starts
+            .select { |name, _line| parser.type_map[name] == :class }
+            .uniq { |name, _line| name }
+
+          class_entries.last || starts.first
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/file_parser/custom_parser.rb

@@ -50,16 +50,23 @@ module AnnotateRb
           }
         end
 
+        def on_const(const)
+          @_last_const_lineno = lineno
+          super
+        end
+
         def on_const_ref(const)
-          add_event(__method__, const, lineno)
-          @block_starts << [const, lineno]
+          declaration_lineno = @_last_const_lineno || lineno
+          add_event(__method__, const, declaration_lineno)
+          @block_starts << [const, declaration_lineno]
           super
         end
 
         # Used for `class Foo::User`
         def on_const_path_ref(_left, const)
-          add_event(__method__, const, lineno)
-          @block_starts << [const, lineno]
+          declaration_lineno = @_last_const_lineno || lineno
+          add_event(__method__, const, declaration_lineno)
+          @block_starts << [const, declaration_lineno]
           super
         end
 

data/lib/annotate_rb/model_annotator/file_parser/magic_comment.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module FileParser
+      module MagicComment
+        DIRECTIVE_KEYS = %w[
+          encoding
+          coding
+          frozen_string_literal
+          warn_indent
+          shareable_constant_value
+          typed
+          rbs_inline
+        ].freeze
+
+        SIMPLE = /\A\s*#\s*(?<key>[A-Za-z][A-Za-z0-9_-]*)\s*:\s*\S/
+        EMACS = /\A\s*#\s*-\*-.*-\*-\s*\z/
+        VIM = /\A\s*#\s*vim:\s/
+
+        def self.match?(line)
+          if (m = SIMPLE.match(line))
+            key = m[:key].downcase.tr("-", "_")
+            return true if DIRECTIVE_KEYS.include?(key)
+          end
+
+          EMACS.match?(line) || VIM.match?(line)
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/file_parser/parsed_file.rb

@@ -6,12 +6,13 @@ module AnnotateRb
       class ParsedFile
         SKIP_ANNOTATION_STRING = "# -*- SkipSchemaAnnotations"
 
-        def initialize(file_content, new_annotations, parser_klass, options)
+        def initialize(file_content, new_annotations, parser_klass, options, model_class_name: nil)
           @file_content = file_content
           @file_lines = @file_content.lines
           @new_annotations = new_annotations
           @parser_klass = parser_klass
           @options = options
+          @model_class_name = model_class_name
         end
 
         def parse
@@ -44,7 +45,7 @@ module AnnotateRb
               annotation_start = @finder.annotation_start
               annotation_end = @finder.annotation_end
 
-              if @file_lines[annotation_start - 1]&.strip&.empty?
+              if annotation_start > 0 && @file_lines[annotation_start - 1]&.strip&.empty?
                 annotation_start -= 1
                 has_leading_whitespace = true
               end
@@ -64,10 +65,8 @@ module AnnotateRb
           annotation_position = nil
 
           if has_annotations
-            const_declaration = @file_parser.starts.first
-
-            # If the file does not have any class or module declaration then const_declaration can be nil
-            _const, line_number = const_declaration
+            target = AnnotationTarget.find(@file_parser, @options, model_class_name: @model_class_name)
+            _const, line_number = target if target
 
             if line_number
               annotation_position = if @finder.annotation_start < line_number

data/lib/annotate_rb/model_annotator/file_parser.rb

@@ -4,7 +4,9 @@ module AnnotateRb
   module ModelAnnotator
     module FileParser
       autoload :AnnotationFinder, "annotate_rb/model_annotator/file_parser/annotation_finder"
+      autoload :AnnotationTarget, "annotate_rb/model_annotator/file_parser/annotation_target"
       autoload :CustomParser, "annotate_rb/model_annotator/file_parser/custom_parser"
+      autoload :MagicComment, "annotate_rb/model_annotator/file_parser/magic_comment"
       autoload :ParsedFile, "annotate_rb/model_annotator/file_parser/parsed_file"
       autoload :ParsedFileResult, "annotate_rb/model_annotator/file_parser/parsed_file_result"
       autoload :YmlParser, "annotate_rb/model_annotator/file_parser/yml_parser"

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

@@ -45,16 +45,27 @@ module AnnotateRb
             end
           end
 
+          comment_info = ""
+          if options[:show_indexes_comments]
+            value = index.try(:comment).try(:to_s)
+            comment_info = if value.present?
+              " COMMENT #{value}"
+            else
+              ""
+            end
+          end
+
           # standard:disable Lint/FormatParameterMismatch
           sprintf(
-            "#  %-#{max_size}.#{max_size}s %s%s%s%s%s%s",
+            "#  %-#{max_size}.#{max_size}s %s%s%s%s%s%s%s",
             index.name,
             "(#{columns_info.join(",")})",
             include_info,
             unique_info,
             nulls_not_distinct_info,
             where_info,
-            using_info
+            using_info,
+            comment_info
           ).rstrip
           # standard:enable Lint/FormatParameterMismatch
         end
@@ -92,13 +103,24 @@ module AnnotateRb
             end
           end
 
+          comment_info = ""
+          if options[:show_indexes_comments]
+            value = index.try(:comment).try(:to_s)
+            comment_info = if value.present?
+              " _comment_ #{value}"
+            else
+              ""
+            end
+          end
+
           details = sprintf(
-            "%s%s%s%s%s",
+            "%s%s%s%s%s%s",
             include_info,
             unique_info,
             nulls_not_distinct_info,
             where_info,
-            using_info
+            using_info,
+            comment_info
           ).strip
           details = " (#{details})" unless details.blank?
 

data/lib/annotate_rb/model_annotator/model_wrapper.rb

@@ -219,6 +219,23 @@ module AnnotateRb
         ]
       end
 
+      def enum_types
+        @enum_types ||=
+          if connection.respond_to?(:enum_types)
+            begin
+              # enum values may be a String or an Array depending on the Rails version.
+              # See: https://github.com/rails/rails/pull/54141
+              connection.enum_types.map do |name, values|
+                [name, values.is_a?(Array) ? values : values.to_s.split(",")]
+              end
+            rescue ActiveRecord::StatementInvalid
+              []
+            end
+          else
+            []
+          end
+      end
+
       def migration_version
         return 0 unless @options[:include_version]
 
@@ -229,7 +246,14 @@ module AnnotateRb
 
         if @options.get_state(cache_key).nil?
           migration_version = begin
-            connection.migration_context.current_version
+            # Rails 7.1+ moved migration_context from ConnectionAdapter to ConnectionPool.
+            # ConnectionAdapter#migration_context was removed in Rails 7.2.
+            # See: https://github.com/rails/rails/pull/51162
+            if connection.pool.respond_to?(:migration_context)
+              connection.pool.migration_context.current_version
+            else
+              connection.migration_context.current_version
+            end
           rescue
             0
           end

data/lib/annotate_rb/model_annotator/project_annotator.rb

@@ -42,13 +42,14 @@ module AnnotateRb
         klass.reset_column_information
         annotation = Annotation::AnnotationBuilder.new(klass, @options).build
         model_name = klass.name.underscore
+        model_class_name = klass.name.demodulize
 
         # 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)
+        model_instruction = SingleFileAnnotatorInstruction.new(file, annotation, :position_in_class, @options, model_class_name: model_class_name)
         instructions << model_instruction
 
         related_files = RelatedFilesListBuilder.new(file, model_name, table_name, @options).build

data/lib/annotate_rb/model_annotator/single_file_annotator.rb

@@ -5,7 +5,7 @@ module AnnotateRb
     class SingleFileAnnotator
       class << self
         def call_with_instructions(instruction)
-          call(instruction.file, instruction.annotation, instruction.position, instruction.options)
+          call(instruction.file, instruction.annotation, instruction.position, instruction.options, model_class_name: instruction.model_class_name)
         end
 
         # Add a schema block to a file. If the file already contains
@@ -21,14 +21,14 @@ module AnnotateRb
         #  :position_in_*<Symbol>:: where to place the annotated section in fixture or model file,
         #                           :before, :top, :after or :bottom. Default is :before.
         #
-        def call(file_name, annotation, annotation_position, options)
+        def call(file_name, annotation, annotation_position, options, model_class_name: nil)
           return false unless File.exist?(file_name)
           old_content = File.read(file_name)
 
           parser_klass = FileToParserMapper.map(file_name)
 
           begin
-            parsed_file = FileParser::ParsedFile.new(old_content, annotation, parser_klass, options).parse
+            parsed_file = FileParser::ParsedFile.new(old_content, annotation, parser_klass, options, model_class_name: model_class_name).parse
           rescue FileParser::AnnotationFinder::MalformedAnnotation => e
             warn "Unable to process #{file_name}: #{e.message}"
             warn "\t" + e.backtrace.join("\n\t") if @options[:trace]
@@ -41,9 +41,9 @@ module AnnotateRb
           abort "AnnotateRb error. #{file_name} needs to be updated, but annotaterb was run with `--frozen`." if options[:frozen]
 
           updated_file_content = if !parsed_file.has_annotations?
-            AnnotatedFile::Generator.new(old_content, annotation, annotation_position, parser_klass, parsed_file, options).generate
+            AnnotatedFile::Generator.new(old_content, annotation, annotation_position, parser_klass, parsed_file, options, model_class_name: model_class_name).generate
           elsif options[:force]
-            AnnotatedFile::Generator.new(old_content, annotation, annotation_position, parser_klass, parsed_file, options).generate
+            AnnotatedFile::Generator.new(old_content, annotation, annotation_position, parser_klass, parsed_file, options, model_class_name: model_class_name).generate
           else
             AnnotatedFile::Updater.new(old_content, annotation, annotation_position, parsed_file, options).update
           end

data/lib/annotate_rb/model_annotator/single_file_annotator_instruction.rb

@@ -4,14 +4,15 @@ module AnnotateRb
   module ModelAnnotator
     # A plain old Ruby object (PORO) that contains all necessary information for SingleFileAnnotator
     class SingleFileAnnotatorInstruction
-      def initialize(file, annotation, position, options)
+      def initialize(file, annotation, position, options, model_class_name: nil)
         @file = file # Path to file
         @annotation = annotation # Annotation string
         @position = position # Position in the file where to write the annotation to
         @options = options
+        @model_class_name = model_class_name # Short class name; set for the model file itself, nil for related files
       end
 
-      attr_reader :file, :annotation, :position, :options
+      attr_reader :file, :annotation, :position, :options, :model_class_name
     end
   end
 end

data/lib/annotate_rb/model_annotator/zeitwerk_class_getter.rb

@@ -49,7 +49,7 @@ module AnnotateRb
 
         # once we have the filepath_relative_to_root_dir, we need to see if it
         # falls within one of our Zeitwerk "collapsed" paths.
-        if loader.collapse.any? { |path| path.include?(root_dir) && file.include?(path.split(root_dir)[1]) }
+        if loader.collapse.any? { |path| path.include?(root_dir) && @file.include?(path.split(root_dir)[1]) }
           # if the file is within a collapsed path, we then need to, for each
           # collapsed path, remove the root dir
           collapsed = loader.collapse.map { |path| path.split(root_dir)[1].sub(/^\//, "") }.to_set

data/lib/annotate_rb/model_annotator.rb

@@ -27,6 +27,7 @@ module AnnotateRb
     autoload :FileParser, "annotate_rb/model_annotator/file_parser"
     autoload :ZeitwerkClassGetter, "annotate_rb/model_annotator/zeitwerk_class_getter"
     autoload :CheckConstraintAnnotation, "annotate_rb/model_annotator/check_constraint_annotation"
+    autoload :EnumAnnotation, "annotate_rb/model_annotator/enum_annotation"
     autoload :FileToParserMapper, "annotate_rb/model_annotator/file_to_parser_mapper"
     autoload :Components, "annotate_rb/model_annotator/components"
     autoload :Annotation, "annotate_rb/model_annotator/annotation"

data/lib/annotate_rb/options.rb

@@ -47,8 +47,10 @@ module AnnotateRb
       include_version: false, # ModelAnnotator
       show_complete_foreign_keys: false, # ModelAnnotator
       show_check_constraints: false, # ModelAnnotator
+      show_enums: false, # ModelAnnotator
       show_foreign_keys: true, # ModelAnnotator
       show_indexes: true, # ModelAnnotator
+      show_indexes_comments: false, # ModelAnnotator
       show_indexes_include: false, # ModelAnnotator
       show_virtual_columns: false, # ModelAnnotator
       simple_indexes: false, # ModelAnnotator
@@ -78,10 +80,10 @@ module AnnotateRb
       ignore_columns: nil, # ModelAnnotator
       ignore_multi_database_name: false, # ModelAnnotator
       ignore_routes: nil, # RouteAnnotator
-      ignore_unknown_models: false, # ModelAnnotator
       models: true, # Core
       routes: false, # Core
       skip_on_db_migrate: false, # Core
+      auto_annotate_routes_after_migrate: false, # Core
       target_action: :do_annotations, # Core; Possible values: :do_annotations, :remove_annotations
       wrapper: nil, # ModelAnnotator, RouteAnnotator
       wrapper_close: nil, # ModelAnnotator, RouteAnnotator
@@ -120,9 +122,11 @@ module AnnotateRb
       :ignore_unknown_models,
       :include_version,
       :show_check_constraints,
+      :show_enums,
       :show_complete_foreign_keys,
       :show_foreign_keys,
       :show_indexes,
+      :show_indexes_comments,
       :show_indexes_include,
       :simple_indexes,
       :sort,
@@ -143,11 +147,11 @@ module AnnotateRb
       :timestamp_columns,
       :ignore_columns,
       :ignore_routes,
-      :ignore_unknown_models,
       :ignore_multi_database_name,
       :models,
       :routes,
       :skip_on_db_migrate,
+      :auto_annotate_routes_after_migrate,
       :target_action,
       :wrapper,
       :wrapper_close,

data/lib/annotate_rb/parser.rb

@@ -22,7 +22,9 @@ module AnnotateRb
       exit: false
     }.freeze
 
-    ANNOTATION_POSITIONS = %w[before top after bottom].freeze
+    ANNOTATION_POSITIONS = %w[before top after bottom before_doc].freeze
+    AFTER_POSITIONS = %w[after bottom].freeze
+    DOC_AWARE_POSITIONS = %w[before_doc].freeze
     FILE_TYPE_POSITIONS = %w[position_in_class position_in_factory position_in_fixture position_in_test position_in_routes position_in_serializer].freeze
     EXCLUSION_LIST = %w[tests fixtures factories serializers].freeze
     FORMAT_TYPES = %w[bare rdoc yard markdown].freeze
@@ -297,9 +299,9 @@ module AnnotateRb
       has_set_position = {}
 
       option_parser.on("-p",
-        "--position [before|top|after|bottom]",
+        "--position [before|top|after|bottom|before_doc]",
         ANNOTATION_POSITIONS,
-        "Place the annotations at the top (before) or the bottom (after) of the model/test/fixture/factory/route/serializer file(s)") do |position|
+        "Place the annotations at the top (before), bottom (after), or above the class documentation (before_doc) of the model/test/fixture/factory/route/serializer file(s)") do |position|
         @options[:position] = position
 
         FILE_TYPE_POSITIONS.each do |key|
@@ -308,9 +310,9 @@ module AnnotateRb
       end
 
       option_parser.on("--pc",
-        "--position-in-class [before|top|after|bottom]",
+        "--position-in-class [before|top|after|bottom|before_doc]",
         ANNOTATION_POSITIONS,
-        "Place the annotations at the top (before) or the bottom (after) of the model file") do |position_in_class|
+        "Place the annotations at the top (before), bottom (after), or above the class documentation (before_doc) of the model file") do |position_in_class|
         @options[:position_in_class] = position_in_class
         has_set_position["position_in_class"] = true
       end

data/lib/annotate_rb/route_annotator/base_processor.rb

@@ -75,7 +75,7 @@ module AnnotateRb
         header_position = 0
 
         content.split(/\n/, -1).each_with_index do |line, line_number|
-          if mode == :header && line !~ /\s*#/
+          if mode == :header && line !~ /\A\s*#/
             mode = :content
             real_content << line unless line.blank?
           elsif mode == :content

data/lib/annotate_rb/route_annotator/helper.rb

@@ -70,7 +70,7 @@ module AnnotateRb
           header_position = 0
 
           content.split(/\n/, -1).each_with_index do |line, line_number|
-            if mode == :header && line !~ /\s*#/
+            if mode == :header && line !~ /\A\s*#/
               mode = :content
               real_content << line unless line.blank?
             elsif mode == :content

data/lib/annotate_rb/runner.rb

@@ -5,10 +5,18 @@ module AnnotateRb
     class << self
       attr_reader :runner
 
-      def run(args)
+      def run_after_migration
+        config_file_options = ConfigLoader.load_config
+        options = Options.from(config_file_options)
+
+        commands = ["models", *(options[:auto_annotate_routes_after_migrate] ? ["routes"] : [])]
+        commands.each { |cmd| run([cmd], config_file_options: config_file_options) }
+      end
+
+      def run(args, config_file_options: nil)
         self.runner = new
 
-        runner.run(args)
+        runner.run(args, config_file_options: config_file_options)
 
         self.runner = nil
       end
@@ -22,14 +30,14 @@ module AnnotateRb
       attr_writer :runner
     end
 
-    def run(args)
+    def run(args, config_file_options: nil)
       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
+      config_file_options = ConfigLoader.load_config if config_file_options.nil?
       options = config_file_options.merge(parsed_options)
 
       @options = Options.from(options, {working_args: remaining_args})

data/lib/annotate_rb/tasks/annotate_models_migrate.rake

@@ -28,11 +28,16 @@ migration_tasks.each do |task|
   next unless Rake::Task.task_defined?(task)
   next if config[:skip_on_db_migrate]
 
-  Rake::Task[task].enhance do # This block is ran after `task` completes
-    task_name = Rake.application.top_level_tasks.last # The name of the task that was run, e.g. "db:migrate"
+  Rake::Task[task].enhance do |current_task| # This block is ran after `task` completes
+    # Prefer the top-level task (the one invoked from the CLI, e.g. "db:migrate") so that
+    # when sub-tasks chain (e.g. db:migrate:redo invokes db:rollback then db:migrate), we
+    # defer the annotation run to after everything completes. Fall back to the currently
+    # enhanced task when there is no top-level task (e.g. when the task is invoked
+    # programmatically from application code rather than from the Rake CLI).
+    task_name = Rake.application.top_level_tasks.last || current_task.name
 
     Rake::Task[task_name].enhance do
-      ::AnnotateRb::Runner.run(["models"])
+      ::AnnotateRb::Runner.run_after_migration
     end
   end
 end

data/lib/generators/annotate_rb/update_config/update_config_generator.rb

@@ -6,7 +6,10 @@ module AnnotateRb
   module Generators
     class UpdateConfigGenerator < ::Rails::Generators::Base
       def generate_config
-        insert_into_file ::AnnotateRb::ConfigFinder::DOTFILE do
+        parsed_options = AnnotateRb::Parser.parse(ARGV, {})
+        AnnotateRb::ConfigFinder.config_path = parsed_options[:config_path] if parsed_options[:config_path]
+
+        insert_into_file ::AnnotateRb::ConfigFinder.find_project_dotfile do
           ::AnnotateRb::ConfigGenerator.unset_config_defaults
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: annotaterb
 version: !ruby/object:Gem::Version
-  version: 4.22.0
+  version: 4.23.0
 platform: ruby
 authors:
 - Andrew W. Lee
@@ -90,10 +90,16 @@ files:
 - lib/annotate_rb/model_annotator/column_annotation/default_value_builder.rb
 - lib/annotate_rb/model_annotator/column_annotation/type_builder.rb
 - lib/annotate_rb/model_annotator/components.rb
+- lib/annotate_rb/model_annotator/enum_annotation.rb
+- lib/annotate_rb/model_annotator/enum_annotation/annotation.rb
+- lib/annotate_rb/model_annotator/enum_annotation/annotation_builder.rb
+- lib/annotate_rb/model_annotator/enum_annotation/enum_component.rb
 - lib/annotate_rb/model_annotator/file_name_resolver.rb
 - lib/annotate_rb/model_annotator/file_parser.rb
 - lib/annotate_rb/model_annotator/file_parser/annotation_finder.rb
+- lib/annotate_rb/model_annotator/file_parser/annotation_target.rb
 - lib/annotate_rb/model_annotator/file_parser/custom_parser.rb
+- lib/annotate_rb/model_annotator/file_parser/magic_comment.rb
 - lib/annotate_rb/model_annotator/file_parser/parsed_file.rb
 - lib/annotate_rb/model_annotator/file_parser/parsed_file_result.rb
 - lib/annotate_rb/model_annotator/file_parser/yml_parser.rb
@@ -164,7 +170,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.4
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A gem for generating annotations for Rails projects.
 test_files: []