annotaterb 4.23.0 → 4.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 249172f3c37299ac55df233909754c48456b629d11517ce03c84fae62232677d
-  data.tar.gz: 9fa726c0abbb3bc7508257d24e7e0f0e4f9a79c94e255909b8bf7162a2f25d9f
+  metadata.gz: ff11e0177eddc61744806ec5749c7a5d234023e0e7d75d46bd5fc21e4d0998fc
+  data.tar.gz: f8c87d260bf6cafbeb120568ecda6131f6bd335ef2c3882630a45cc2e6631a05
 SHA512:
-  metadata.gz: f695ccb014c329b7c897f1832c4bb053df9fbec718198d68466884585b17f17fbfb6805a053024a38133196f7d9934aaff56d89c83598160966b1fc4dcaaaa3c
-  data.tar.gz: 73994c40f74a0c793cd974cf1369b59403e3b3a49ce6c643b661f9dfdffb7425dcfbb96c98ba2a23c3347861fa4cd759be380613d92627cb4046956af249dea3
+  metadata.gz: 6e2edbfc22db4f8b1bd150313e795993e3f5366ac4594084fec2f7ee9f1d2650d98cef0933bdc92a0ff0a4e52af4bb77b35672cbd0049fed9c8e6c256743e00e
+  data.tar.gz: ddf3161a49b9c041083ce42c9264823da16e23703a8f013b98098f24dc4f7d46642a659621f0d0612572865fec1099a91e7622139acc3a1c689e7df1d96e81bf

data/CHANGELOG.md

@@ -1,9 +1,67 @@
 # 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)
@@ -13,8 +71,6 @@
 - 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:**
 
@@ -22,7 +78,7 @@
 - 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)**
+- 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))

data/README.md

@@ -237,6 +237,122 @@ 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.

data/VERSION

@@ -1 +1 @@
-4.23.0
+4.24.0

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

@@ -27,6 +27,8 @@ 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
             ]
@@ -65,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,
@@ -74,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/exclusion_constraint_annotation/annotation.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ExclusionConstraintAnnotation
+      class Annotation
+        HEADER_TEXT = "Exclusion Constraints"
+
+        def initialize(constraints)
+          @constraints = constraints
+        end
+
+        def body
+          [
+            Components::BlankCommentLine.new,
+            Components::Header.new(HEADER_TEXT),
+            Components::BlankCommentLine.new,
+            *@constraints
+          ]
+        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/exclusion_constraint_annotation/annotation_builder.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ExclusionConstraintAnnotation
+      class AnnotationBuilder
+        def initialize(model, options)
+          @model = model
+          @options = options
+        end
+
+        def build
+          return Components::NilComponent.new if !@options[:show_exclusion_constraints]
+          return Components::NilComponent.new unless @model.connection.respond_to?(:supports_exclusion_constraints?) &&
+            @model.connection.supports_exclusion_constraints? && @model.connection.respond_to?(:exclusion_constraints)
+
+          exclusion_constraints = @model.connection.exclusion_constraints(@model.table_name)
+          return Components::NilComponent.new if exclusion_constraints.empty?
+
+          max_size = exclusion_constraints.map { |exclusion_constraint| exclusion_constraint.name.size }.max + 1
+
+          constraints = exclusion_constraints.sort_by(&:name).map do |exclusion_constraint|
+            details = "(#{exclusion_constraint.expression})"
+            details += " USING #{exclusion_constraint.using}" if exclusion_constraint.using
+            details += " WHERE (#{exclusion_constraint.where})" if exclusion_constraint.where
+            if exclusion_constraint.deferrable
+              details += " DEFERRABLE INITIALLY #{exclusion_constraint.deferrable.to_s.upcase}"
+            end
+
+            ExclusionConstraintComponent.new(exclusion_constraint.name, details, max_size)
+          end
+
+          _annotation = Annotation.new(constraints)
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/exclusion_constraint_annotation/exclusion_constraint_component.rb

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

data/lib/annotate_rb/model_annotator/exclusion_constraint_annotation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ExclusionConstraintAnnotation
+      autoload :AnnotationBuilder, "annotate_rb/model_annotator/exclusion_constraint_annotation/annotation_builder"
+      autoload :Annotation, "annotate_rb/model_annotator/exclusion_constraint_annotation/annotation"
+      autoload :ExclusionConstraintComponent, "annotate_rb/model_annotator/exclusion_constraint_annotation/exclusion_constraint_component"
+    end
+  end
+end

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

@@ -19,9 +19,19 @@ module AnnotateRb
         SCHEMA_HEADER_EXACT = [
           IndexAnnotation::Annotation::HEADER_TEXT,
           ForeignKeyAnnotation::Annotation::HEADER_TEXT,
-          CheckConstraintAnnotation::Annotation::HEADER_TEXT
+          CheckConstraintAnnotation::Annotation::HEADER_TEXT,
+          UniqueConstraintAnnotation::Annotation::HEADER_TEXT,
+          ExclusionConstraintAnnotation::Annotation::HEADER_TEXT,
+          EnumAnnotation::Annotation::HEADER_TEXT
         ].freeze
 
+        # `format_markdown: true` renders each of the section headers above as
+        # "### <name>" instead of "<name>", so SCHEMA_HEADER_EXACT can't match it directly.
+        # There's no HEADER_TEXT constant for the columns table itself,
+        # so "Columns" is listed explicitly here.
+        MARKDOWN_HEADER_PREFIX = "### "
+        MARKDOWN_SECTION_HEADERS = (SCHEMA_HEADER_EXACT + ["Columns"]).freeze
+
         class MalformedAnnotation < StandardError; end
 
         class NoAnnotationFound < StandardError; end
@@ -118,7 +128,18 @@ module AnnotateRb
           ending
         end
 
-        # Tabular rows have ≥2 leading spaces after `#`; prose has at most one.
+        # A line is part of the schema block if it matches one of the known
+        # header prefixes/exact texts, or if it looks like a tabular/list row
+        # of the annotation body:
+        #
+        # - Default/plain format: rows have >= 2 leading spaces after `#`
+        #   (e.g. "#  id  :integer  not null"); prose has at most one.
+        # - Markdown format (`format_markdown: true`) instead uses a single
+        #   leading space after `#` for everything, so it needs its own
+        #   detection: "### <name>" section headers (matched against
+        #   MARKDOWN_SECTION_HEADERS with the prefix stripped), "|"-delimited
+        #   table rows (header/divider/data), and "* `...`" bulleted list
+        #   items for indexes/foreign keys/enums.
         def schema_like?(comment)
           return true if comment == DEFAULT_ANNOTATION_ENDING
 
@@ -128,6 +149,21 @@ module AnnotateRb
           return true if SCHEMA_HEADER_PREFIXES.any? { |p| text.start_with?(p) }
           return true if SCHEMA_HEADER_EXACT.include?(text)
 
+          # Markdown section headers, e.g. "### Columns", "### Indexes".
+          if text.start_with?(MARKDOWN_HEADER_PREFIX)
+            return MARKDOWN_SECTION_HEADERS.include?(text.delete_prefix(MARKDOWN_HEADER_PREFIX))
+          end
+
+          # Requires at least two | separators to identify Markdown tables.
+          # This prevents normal user comments containing a single | from being mistaken for a table.
+          return true if text.count("|") >= 2
+
+          # Markdown bulleted list items used for foreign keys/indexes/enums,
+          # e.g. "* `index_name`:" or the nested "    * **`column`**". The
+          # backtick right after the bullet marker distinguishes these from
+          # an unrelated user comment that starts with a plain "* ".
+          return true if text.match?(/\A\s*\*\s+\*{0,2}`/)
+
           comment.match?(/\A#\s{2,}\S/)
         end
       end

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

@@ -43,10 +43,20 @@ module AnnotateRb
           begin
             parser.parse(@input)
           rescue Psych::SyntaxError => _e
-            # "Dynamic fixtures with ERB" exist in Rails, and will cause Psych.parser to error
-            # This is a hacky solution to get around this and still have it parse
-            erb_yml = ERB.new(@input).result
-            parser.parse(erb_yml)
+            # "Dynamic fixtures with ERB" exist in Rails and cause Psych.parser to error.
+            #
+            # We deliberately do not evaluate the ERB and read line numbers off the
+            # result: evaluating runs arbitrary code, and the line numbers from the
+            # evaluated output do not map back to the original file (ERB tags spanning
+            # multiple lines shift the offsets), which would place annotations inside
+            # an ERB tag. Instead we derive the content bounds straight from the
+            # original lines so annotations land around the ERB body.
+            #
+            # Only fall back for actual ERB fixtures. Genuinely malformed YAML
+            # (no ERB tags) should keep surfacing the parse error rather than
+            # being silently annotated.
+            raise unless erb_fixture?
+            return record_erb_positions
           end
 
           stream = parser.handler.root
@@ -68,6 +78,35 @@ module AnnotateRb
             @ends << [nil, stream.end_line]
           end
         end
+
+        # Locates the content bounds of an ERB fixture directly from the original
+        # lines, treating the ERB/YAML body as the doc. The start is the first
+        # non-blank, non-comment line so annotations are written above the ERB
+        # block (and after any leading comments), never inside a tag.
+        def record_erb_positions
+          lines = @input.split($/)
+          content_start = lines.index { |line| content_line?(line) }
+
+          if content_start.nil?
+            @starts << [nil, 0]
+            @ends << [nil, 0]
+          else
+            content_end = lines.rindex { |line| content_line?(line) }
+            @starts << [nil, content_start]
+            @ends << [nil, content_end + 1]
+          end
+        end
+
+        def content_line?(line)
+          stripped = line.strip
+          !stripped.empty? && !stripped.start_with?("#")
+        end
+
+        # True when the input contains an ERB tag, i.e. it is a dynamic fixture
+        # rather than plain (possibly malformed) YAML.
+        def erb_fixture?
+          @input.match?(/<%.*?%>/m)
+        end
       end
     end
   end

data/lib/annotate_rb/model_annotator/foreign_key_annotation/foreign_key_component_builder.rb

@@ -32,6 +32,12 @@ module AnnotateRb
             constraints_info = ""
             constraints_info += "ON DELETE => #{foreign_key.on_delete} " if foreign_key.on_delete
             constraints_info += "ON UPDATE => #{foreign_key.on_update} " if foreign_key.on_update
+            if foreign_key.respond_to?(:deferrable) && foreign_key.deferrable
+              # Rails 7.0's extract_foreign_key_deferrable returns `true` for the initially-immediate case;
+              # 7.1+ normalized this to `:immediate`. Map `true` back to IMMEDIATE so we don't emit "INITIALLY TRUE".
+              initially = (foreign_key.deferrable == true) ? "IMMEDIATE" : foreign_key.deferrable.to_s.upcase
+              constraints_info += "DEFERRABLE INITIALLY #{initially} "
+            end
             constraints_info.strip
           end
         end

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

@@ -15,6 +15,9 @@ module AnnotateRb
           indexes = @model.retrieve_indexes_from_table
           return Components::NilComponent.new if indexes.empty?
 
+          indexes = reject_constraint_backed_indexes(indexes)
+          return Components::NilComponent.new if indexes.empty?
+
           max_size = indexes.map { |index| index.name.size }.max + 1
 
           indexes = indexes.sort_by(&:name).map do |index|
@@ -23,6 +26,32 @@ module AnnotateRb
 
           _annotation = Annotation.new(indexes)
         end
+
+        private
+
+        # Mirrors ActiveRecord's schema_dumper#indexes_in_create: PostgreSQL's
+        # unique and exclusion constraints are backed by indexes with the same
+        # name, so those show up in `connection.indexes` too. Drop them here so
+        # they only appear under their dedicated sections.
+        def reject_constraint_backed_indexes(indexes)
+          connection = @model.connection
+
+          if connection.respond_to?(:supports_exclusion_constraints?) &&
+              connection.supports_exclusion_constraints? &&
+              connection.respond_to?(:exclusion_constraints)
+            excl_names = connection.exclusion_constraints(@model.table_name).map(&:name)
+            indexes = indexes.reject { |index| excl_names.include?(index.name) }
+          end
+
+          if connection.respond_to?(:supports_unique_constraints?) &&
+              connection.supports_unique_constraints? &&
+              connection.respond_to?(:unique_constraints)
+            unique_names = connection.unique_constraints(@model.table_name).map(&:name)
+            indexes = indexes.reject { |index| unique_names.include?(index.name) }
+          end
+
+          indexes
+        end
       end
     end
   end

data/lib/annotate_rb/model_annotator/model_wrapper.rb

@@ -68,8 +68,20 @@ module AnnotateRb
           connection.table_comment(@klass.table_name).present?
       end
 
+      # Returns column defaults for annotations.
+      #
+      # `Model#column_defaults` reflects `attribute :foo, default: X` overrides,
+      # which would incorrectly show the Ruby-side default in annotations
+      # instead of the DB schema default. To preserve model-level decorations
+      # such as `TimeZoneConverter` on datetime columns, we start from
+      # `column_defaults` and only substitute the DB schema value when a
+      # difference indicates an attribute-level override.
       def column_defaults
-        @klass.column_defaults
+        @column_defaults ||= @klass.column_defaults.each_with_object({}) do |(name, value), result|
+          column = @klass.columns_hash[name]
+          schema_value = schema_default_for(column)
+          result[name] = (value == schema_value) ? value : schema_value
+        end
       end
 
       # Add columns managed by the globalize gem if this gem is being used.
@@ -263,6 +275,26 @@ module AnnotateRb
 
         @options.get_state(cache_key)
       end
+
+      private
+
+      def schema_default_for(column)
+        return nil if column.nil? || column.default.nil? || column.default_function
+        cast_type_for(column).deserialize(column.default)
+      end
+
+      # Rails post-8.1 exposes `Column#cast_type` directly; Rails 8.1 introduced
+      # the transitional `Column#fetch_cast_type(connection)`; older versions
+      # required `connection.lookup_cast_type_from_column(column)`.
+      def cast_type_for(column)
+        if column.respond_to?(:cast_type)
+          column.cast_type
+        elsif column.respond_to?(:fetch_cast_type)
+          column.fetch_cast_type(connection)
+        else
+          connection.lookup_cast_type_from_column(column)
+        end
+      end
     end
   end
 end

data/lib/annotate_rb/model_annotator/single_file_annotation_remover.rb

@@ -18,7 +18,7 @@ module AnnotateRb
             parsed_file = FileParser::ParsedFile.new(old_content, "", parser_klass, options).parse
           rescue FileParser::AnnotationFinder::MalformedAnnotation => e
             warn "Unable to process #{file_name}: #{e.message}"
-            warn "\t" + e.backtrace.join("\n\t") if @options[:trace]
+            warn "\t" + e.backtrace.join("\n\t") if options[:trace]
             return false
           end
 

data/lib/annotate_rb/model_annotator/single_file_annotator.rb

@@ -31,7 +31,7 @@ module AnnotateRb
             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]
+            warn "\t" + e.backtrace.join("\n\t") if options[:trace]
             return false
           end
 

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module UniqueConstraintAnnotation
+      class Annotation
+        HEADER_TEXT = "Unique Constraints"
+
+        def initialize(constraints)
+          @constraints = constraints
+        end
+
+        def body
+          [
+            Components::BlankCommentLine.new,
+            Components::Header.new(HEADER_TEXT),
+            Components::BlankCommentLine.new,
+            *@constraints
+          ]
+        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/unique_constraint_annotation/annotation_builder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module UniqueConstraintAnnotation
+      class AnnotationBuilder
+        def initialize(model, options)
+          @model = model
+          @options = options
+        end
+
+        def build
+          return Components::NilComponent.new if !@options[:show_unique_constraints]
+          return Components::NilComponent.new unless @model.connection.respond_to?(:supports_unique_constraints?) &&
+            @model.connection.supports_unique_constraints? && @model.connection.respond_to?(:unique_constraints)
+
+          unique_constraints = @model.connection.unique_constraints(@model.table_name)
+          return Components::NilComponent.new if unique_constraints.empty?
+
+          max_size = unique_constraints.map { |unique_constraint| unique_constraint.name.size }.max + 1
+
+          constraints = unique_constraints.sort_by(&:name).map do |unique_constraint|
+            columns = Array(unique_constraint.column)
+            details = "(#{columns.join(", ")})"
+            if unique_constraint.deferrable
+              details += " DEFERRABLE INITIALLY #{unique_constraint.deferrable.to_s.upcase}"
+            end
+
+            UniqueConstraintComponent.new(unique_constraint.name, details, max_size)
+          end
+
+          _annotation = Annotation.new(constraints)
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/unique_constraint_annotation/unique_constraint_component.rb

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

data/lib/annotate_rb/model_annotator/unique_constraint_annotation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module UniqueConstraintAnnotation
+      autoload :AnnotationBuilder, "annotate_rb/model_annotator/unique_constraint_annotation/annotation_builder"
+      autoload :Annotation, "annotate_rb/model_annotator/unique_constraint_annotation/annotation"
+      autoload :UniqueConstraintComponent, "annotate_rb/model_annotator/unique_constraint_annotation/unique_constraint_component"
+    end
+  end
+end

data/lib/annotate_rb/model_annotator.rb

@@ -27,6 +27,8 @@ 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 :UniqueConstraintAnnotation, "annotate_rb/model_annotator/unique_constraint_annotation"
+    autoload :ExclusionConstraintAnnotation, "annotate_rb/model_annotator/exclusion_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"

data/lib/annotate_rb/options.rb

@@ -42,11 +42,14 @@ module AnnotateRb
       format_yard: false, # ModelAnnotator
       frozen: false, # ModelAnnotator, but should be used by both
       grouped_polymorphic: false, # ModelAnnotator
+      ignore_database_name: false, # ModelAnnotator
       ignore_model_sub_dir: false, # ModelAnnotator
       ignore_unknown_models: false, # ModelAnnotator
       include_version: false, # ModelAnnotator
       show_complete_foreign_keys: false, # ModelAnnotator
       show_check_constraints: false, # ModelAnnotator
+      show_unique_constraints: false, # ModelAnnotator
+      show_exclusion_constraints: false, # ModelAnnotator
       show_enums: false, # ModelAnnotator
       show_foreign_keys: true, # ModelAnnotator
       show_indexes: true, # ModelAnnotator
@@ -118,10 +121,13 @@ module AnnotateRb
       :format_yard,
       :frozen,
       :grouped_polymorphic,
+      :ignore_database_name,
       :ignore_model_sub_dir,
       :ignore_unknown_models,
       :include_version,
       :show_check_constraints,
+      :show_unique_constraints,
+      :show_exclusion_constraints,
       :show_enums,
       :show_complete_foreign_keys,
       :show_foreign_keys,

data/lib/annotate_rb/parser.rb

@@ -207,6 +207,16 @@ module AnnotateRb
         @options[:show_check_constraints] = true
       end
 
+      option_parser.on("--show-unique-constraints",
+        "List the table's unique constraints in the annotation") do
+        @options[:show_unique_constraints] = true
+      end
+
+      option_parser.on("--show-exclusion-constraints",
+        "List the table's exclusion constraints in the annotation") do
+        @options[:show_exclusion_constraints] = true
+      end
+
       option_parser.on("--hide-limit-column-types VALUES",
         "don't show limit for given column types, separated by commas (i.e., `integer,boolean,text`)") do |values|
         @options[:hide_limit_column_types] = values.to_s
@@ -222,6 +232,11 @@ module AnnotateRb
         @options[:ignore_unknown_models] = true
       end
 
+      option_parser.on("--ignore-database-name",
+        "don't include the database name in the annotation") do
+        @options[:ignore_database_name] = true
+      end
+
       option_parser.on("-I",
         "--ignore-columns REGEX",
         "don't annotate columns that match a given REGEX (i.e., `annotate -I '^(id|updated_at|created_at)'`") do |regex|
@@ -234,7 +249,7 @@ module AnnotateRb
       end
 
       option_parser.on("--without-comment",
-        "include database comments in model annotations") do
+        "exclude database comments in model annotations") do
         @options[:with_comment] = false
       end
 

data/lib/annotate_rb/runner.rb

@@ -46,8 +46,6 @@ module AnnotateRb
       raise "Didn't specify a command" unless @options[:command]
 
       @options[:command].call(@options)
-
-      # TODO
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: annotaterb
 version: !ruby/object:Gem::Version
-  version: 4.23.0
+  version: 4.24.0
 platform: ruby
 authors:
 - Andrew W. Lee
@@ -94,6 +94,10 @@ files:
 - 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/exclusion_constraint_annotation.rb
+- lib/annotate_rb/model_annotator/exclusion_constraint_annotation/annotation.rb
+- lib/annotate_rb/model_annotator/exclusion_constraint_annotation/annotation_builder.rb
+- lib/annotate_rb/model_annotator/exclusion_constraint_annotation/exclusion_constraint_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
@@ -124,6 +128,10 @@ files:
 - lib/annotate_rb/model_annotator/single_file_annotator.rb
 - lib/annotate_rb/model_annotator/single_file_annotator_instruction.rb
 - lib/annotate_rb/model_annotator/single_file_remove_annotation_instruction.rb
+- lib/annotate_rb/model_annotator/unique_constraint_annotation.rb
+- lib/annotate_rb/model_annotator/unique_constraint_annotation/annotation.rb
+- lib/annotate_rb/model_annotator/unique_constraint_annotation/annotation_builder.rb
+- lib/annotate_rb/model_annotator/unique_constraint_annotation/unique_constraint_component.rb
 - lib/annotate_rb/model_annotator/zeitwerk_class_getter.rb
 - lib/annotate_rb/options.rb
 - lib/annotate_rb/parser.rb