annotaterb 4.22.0 → 4.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2be17a236402d5406e2f4d1f68a567bf51de51f924f66591adf9460bfacabe18
-  data.tar.gz: 48743c136f9a195bb1dbaa564bd8047c16411394a991b4c86b57a70844d0e121
+  metadata.gz: ff11e0177eddc61744806ec5749c7a5d234023e0e7d75d46bd5fc21e4d0998fc
+  data.tar.gz: f8c87d260bf6cafbeb120568ecda6131f6bd335ef2c3882630a45cc2e6631a05
 SHA512:
-  metadata.gz: a203a269dbcf4c42a082a2088c6c38d8c4b97c3bbf9ab760762e3149294fb38dc31799aea2f3ece425504782cd2027187bd161ccf4a9c006aaa7a9a791094311
-  data.tar.gz: 8cc55f09f193f5f428db97afc1270386a06eb8185773cfd339830e1ee8e49631a1f203cced676fdb2f4d7d5c0b690f5aadc9108f63d3de588c019d7585c0011b
+  metadata.gz: 6e2edbfc22db4f8b1bd150313e795993e3f5366ac4594084fec2f7ee9f1d2650d98cef0933bdc92a0ff0a4e52af4bb77b35672cbd0049fed9c8e6c256743e00e
+  data.tar.gz: ddf3161a49b9c041083ce42c9264823da16e23703a8f013b98098f24dc4f7d46642a659621f0d0612572865fec1099a91e7622139acc3a1c689e7df1d96e81bf

data/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## [v4.23.0](https://github.com/drwl/annotaterb/tree/v4.23.0) (2026-06-25)
+
+[Full Changelog](https://github.com/drwl/annotaterb/compare/v4.22.0...v4.23.0)
+
+**Implemented enhancements:**
+
+- \[Request\] Support for multiple serializers for one model [\#329](https://github.com/drwl/annotaterb/issues/329)
+- Support COMMENT on an INDEX [\#258](https://github.com/drwl/annotaterb/issues/258)
+
+**Fixed bugs:**
+
+- Re-running annotaterb strips indentation from nested \(indented\) schema annotations [\#332](https://github.com/drwl/annotaterb/issues/332)
+- Setting all sort options to `false` sometimes doesn't respect migration/DB order [\#237](https://github.com/drwl/annotaterb/issues/237)
+
+**Closed issues:**
+
+- mistake post please delete this [\#314](https://github.com/drwl/annotaterb/issues/314)
+- Removal of final empty comment line after foreign keys results in duplicate `fk_rails_...` line [\#297](https://github.com/drwl/annotaterb/issues/297)
+- Default settings does not indent correctly inside a module [\#271](https://github.com/drwl/annotaterb/issues/271)
+- Top does not do what I think it should?  And annotator fails to indent. [\#202](https://github.com/drwl/annotaterb/issues/202)
+- annotaterb is moving my class doc [\#201](https://github.com/drwl/annotaterb/issues/201)
+
+**Merged pull requests:**
+
+- Bump version to v4.23.0 [\#347](https://github.com/drwl/annotaterb/pull/347) ([drwl](https://github.com/drwl))
+- Bump actions/checkout from 6 to 7 [\#346](https://github.com/drwl/annotaterb/pull/346) ([dependabot[bot]](https://github.com/apps/dependabot))
+- Fix duplicate annotations when a file ends with a trailing blank line [\#342](https://github.com/drwl/annotaterb/pull/342) ([OdenTakashi](https://github.com/OdenTakashi))
+- Fix update\_config for non-default config locations [\#341](https://github.com/drwl/annotaterb/pull/341) ([OdenTakashi](https://github.com/OdenTakashi))
+- Fix NameError in ZeitwerkClassGetter for collapsed Zeitwerk paths [\#339](https://github.com/drwl/annotaterb/pull/339) ([KaiyuanMa](https://github.com/KaiyuanMa))
+- Fix annotation inserted inside module when doc comment is present [\#338](https://github.com/drwl/annotaterb/pull/338) ([OdenTakashi](https://github.com/OdenTakashi))
+-   Add `position_in_class: after_doc` to keep class doc adjacent to class [\#337](https://github.com/drwl/annotaterb/pull/337) ([yamat47](https://github.com/yamat47))
+- Fix annotation placement above inner class declarations under `nested_position` [\#336](https://github.com/drwl/annotaterb/pull/336) ([yamat47](https://github.com/yamat47))
+- Drop Ruby \< 3.3 from CI matrix [\#335](https://github.com/drwl/annotaterb/pull/335) ([drwl](https://github.com/drwl))
+- Fix annotation placement in nested files and around trailing user comments [\#334](https://github.com/drwl/annotaterb/pull/334) ([yamat47](https://github.com/yamat47))
+- Preserve indentation when re-running annotaterb on nested-position annotations. [\#333](https://github.com/drwl/annotaterb/pull/333) ([yamat47](https://github.com/yamat47))
+- Respect `--config-path` during config loading [\#331](https://github.com/drwl/annotaterb/pull/331) ([OdenTakashi](https://github.com/OdenTakashi))
+- Fall back to current task when no top-level task is set [\#328](https://github.com/drwl/annotaterb/pull/328) ([jordan-brough](https://github.com/jordan-brough))
+- Fix --show-migration option not working on Rails 7.2+. [\#327](https://github.com/drwl/annotaterb/pull/327) ([OdenTakashi](https://github.com/OdenTakashi))
+- Exit with non-zero code when database is not accessible [\#326](https://github.com/drwl/annotaterb/pull/326) ([OdenTakashi](https://github.com/OdenTakashi))
+- fix potential ReDoS in route annotator regex [\#325](https://github.com/drwl/annotaterb/pull/325) ([OdenTakashi](https://github.com/OdenTakashi))
+- Support opt-in display of PostgreSQL enum types in annotations [\#324](https://github.com/drwl/annotaterb/pull/324) ([OdenTakashi](https://github.com/OdenTakashi))
+- Fix error when column comments contain `%` [\#322](https://github.com/drwl/annotaterb/pull/322) ([willnet](https://github.com/willnet))
+- Add unit tests for AnnotateRb::Helper [\#321](https://github.com/drwl/annotaterb/pull/321) ([OdenTakashi](https://github.com/OdenTakashi))
+- Migrate issue templates to folder-based format [\#320](https://github.com/drwl/annotaterb/pull/320) ([OdenTakashi](https://github.com/OdenTakashi))
+- Add opt-in show\_indexes\_comments option to display index comments [\#319](https://github.com/drwl/annotaterb/pull/319) ([olleolleolle](https://github.com/olleolleolle))
+- Only connect SecondaryRecord to secondary DB when MULTI\_DB\_TEST is set [\#318](https://github.com/drwl/annotaterb/pull/318) ([OdenTakashi](https://github.com/OdenTakashi))
+- Correct secondary database setup in dummy app [\#317](https://github.com/drwl/annotaterb/pull/317) ([OdenTakashi](https://github.com/OdenTakashi))
+- Remove duplicate ignore\_unknown\_models option definition [\#316](https://github.com/drwl/annotaterb/pull/316) ([OdenTakashi](https://github.com/OdenTakashi))
+- Fix column annotation alignment for CJK and fullwidth characters [\#315](https://github.com/drwl/annotaterb/pull/315) ([SergeyGildenshtern](https://github.com/SergeyGildenshtern))
+- Added command example for applying annotations to README [\#313](https://github.com/drwl/annotaterb/pull/313) ([zackerms](https://github.com/zackerms))
+- Generate changelog for v4.22.0 [\#311](https://github.com/drwl/annotaterb/pull/311) ([drwl](https://github.com/drwl))
+- Add opt-in support for automatically annotating routes after migration tasks [\#293](https://github.com/drwl/annotaterb/pull/293) ([OdenTakashi](https://github.com/OdenTakashi))
+
+## [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)
+
+**Implemented enhancements:**
+
+- 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)
+
+**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)
+
+**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))
+- 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,151 @@ 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).
 
+### Configuration options
+
+Keys use snake_case and match the gem defaults in `AnnotateRb::Options`. CLI flags override values from the config file.
+
+#### Position
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `position` | `before` | Fallback position for all `position_in_*` options. One of `before`, `top`, `after`, `bottom`, `before_doc`. |
+| `position_in_class` | `before` | Position in model files. `before_doc` keeps class documentation adjacent to the class. |
+| `position_in_factory` | `before` | Position in FactoryBot factory files. |
+| `position_in_fixture` | `before` | Position in fixture files. |
+| `position_in_test` | `before` | Position in test/spec files. |
+| `position_in_routes` | `before` | Position in `config/routes.rb`. |
+| `position_in_serializer` | `before` | Position in serializer files. |
+| `position_in_additional_file_patterns` | `before` | Position in files matched by `additional_file_patterns`. |
+| `nested_position` | `false` | Place annotations directly above nested classes/modules instead of at the top of the file. |
+
+#### Schema annotation content
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `show_foreign_keys` | `true` | List foreign key constraints. |
+| `show_complete_foreign_keys` | `false` | Use complete foreign key names. |
+| `show_indexes` | `true` | List table indexes. |
+| `show_indexes_comments` | `false` | Include index comments. |
+| `show_indexes_include` | `false` | Include `INCLUDE` columns on indexes. |
+| `simple_indexes` | `false` | Concat related indexes onto each column line. |
+| `show_check_constraints` | `false` | List check constraints. |
+| `show_enums` | `false` | Show PostgreSQL enum types. |
+| `show_virtual_columns` | `false` | Show virtual/generated columns. |
+| `include_version` | `false` | Include the migration version number. |
+| `with_comment` | `true` | Include database comments (fallback for column/table comment flags). |
+| `with_column_comments` | `true` | Include column comments. |
+| `with_table_comments` | `true` | Include table comments. |
+| `position_of_column_comment` | `with_name` | Column comment placement: `with_name` or `rightmost_column`. |
+| `hide_default_column_types` | `""` | Comma-separated column types that omit defaults (e.g. `json,jsonb,hstore`). |
+| `hide_limit_column_types` | `""` | Comma-separated column types that omit limits (e.g. `integer,boolean,text`). |
+| `ignore_columns` | `null` | Regex of column names to skip. |
+| `ignore_database_name` | `false` | Omit the database name from annotations. |
+| `ignore_multi_database_name` | `false` | Omit the database name in multi-database setups. |
+| `timestamp_columns` | `[created_at, updated_at]` | Column names treated as timestamps for classified sorting. |
+| `classes_default_to_s` | `[]` | Class names whose default values are rendered with `to_s`. |
+
+#### Sorting and format
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `sort` | `false` | Sort columns alphabetically. |
+| `classified_sort` | `true` | Sort as id → other columns → timestamps → associations. |
+| `grouped_polymorphic` | `false` | Group polymorphic associations when using `classified_sort`. |
+| `format_markdown` | `false` | Render annotations as Markdown. |
+| `format_rdoc` | `false` | Render annotations as RDoc. |
+| `format_yard` | `false` | Render annotations as YARD. |
+
+#### What to annotate / exclude
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `active_admin` | `false` | Annotate ActiveAdmin models. |
+| `exclude_controllers` | `true` | Skip controller files. |
+| `exclude_factories` | `false` | Skip factory files. |
+| `exclude_fixtures` | `false` | Skip fixture files. |
+| `exclude_helpers` | `true` | Skip helper files. |
+| `exclude_scaffolds` | `true` | Skip scaffold files. |
+| `exclude_serializers` | `false` | Skip serializer files. |
+| `exclude_sti_subclasses` | `false` | Skip STI subclasses. |
+| `exclude_tests` | `false` | Skip test/spec files. Can also be an array of symbols. |
+| `ignore_model_sub_dir` | `false` | Ignore subdirectories under `model_dir`. |
+| `ignore_unknown_models` | `false` | Suppress warnings for bad model files. |
+
+#### Paths
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `model_dir` | `[app/models]` | Directories containing models. |
+| `root_dir` | `[""]` | Root directories for multi-project layouts. |
+| `additional_file_patterns` | `[]` | Extra paths/globs to annotate (supports `%MODEL_NAME%`). |
+| `require` | `[]` | Extra files to require before loading models. |
+
+#### Routes
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `ignore_routes` | `null` | Regex of routes to skip. |
+| `timestamp` | `false` | Include a timestamp in route annotations. |
+| `auto_annotate_routes_after_migrate` | `false` | Also annotate routes after DB migrate tasks. |
+
+#### Wrappers and behavior
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `wrapper` | `null` | Text used for both opening and closing wrappers. |
+| `wrapper_open` | `null` | Opening wrapper text (falls back to `wrapper`). |
+| `wrapper_close` | `null` | Closing wrapper text (falls back to `wrapper`). |
+| `force` | `false` | Rewrite annotations even when unchanged. |
+| `frozen` | `false` | Exit non-zero if annotations would change. |
+| `skip_on_db_migrate` | `false` | Skip automatic annotation after DB migrate tasks. |
+| `debug` | `false` | Print resolved options for debugging. |
+| `trace` | `false` | Print full stack traces when annotation fails. |
+
+Example:
+
+```yml
+# .annotaterb.yml
+position: after
+show_foreign_keys: true
+show_indexes: true
+show_enums: true
+classified_sort: true
+model_dir:
+  - app/models
+  - app/models/concerns
+skip_on_db_migrate: false
+```
+
+### 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.24.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,9 @@ module AnnotateRb
               IndexAnnotation::AnnotationBuilder.new(@model, @options).build,
               ForeignKeyAnnotation::AnnotationBuilder.new(@model, @options).build,
               CheckConstraintAnnotation::AnnotationBuilder.new(@model, @options).build,
+              UniqueConstraintAnnotation::AnnotationBuilder.new(@model, @options).build,
+              ExclusionConstraintAnnotation::AnnotationBuilder.new(@model, @options).build,
+              EnumAnnotation::AnnotationBuilder.new(@model, @options).build,
               SchemaFooter.new
             ]
           end
@@ -64,7 +67,7 @@ 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?
+          database_name = @model.database_name if show_database_name?
 
           _annotation = Annotation.new(@options,
             version: version, table_name: table_name, table_comment: table_comment,
@@ -73,6 +76,11 @@ module AnnotateRb
 
         private
 
+        # TODO: Consolidate ignore_database_name and ignore_multi_database_name; they serve the same purpose
+        def show_database_name?
+          !@options[:ignore_database_name] && multi_db_environment?
+        end
+
         def multi_db_environment?
           return false if @options[:ignore_multi_database_name]
 

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