annotaterb 4.24.0 → 4.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff11e0177eddc61744806ec5749c7a5d234023e0e7d75d46bd5fc21e4d0998fc
-  data.tar.gz: f8c87d260bf6cafbeb120568ecda6131f6bd335ef2c3882630a45cc2e6631a05
+  metadata.gz: e76c98c2c18b7021f7844189a076f4d5cb52b61777c5200bff9888497d3924d2
+  data.tar.gz: ddf7481ef3fdb08071855c9131a7dfca2426d29ad0c7dfdeff9f891d510a867b
 SHA512:
-  metadata.gz: 6e2edbfc22db4f8b1bd150313e795993e3f5366ac4594084fec2f7ee9f1d2650d98cef0933bdc92a0ff0a4e52af4bb77b35672cbd0049fed9c8e6c256743e00e
-  data.tar.gz: ddf3161a49b9c041083ce42c9264823da16e23703a8f013b98098f24dc4f7d46642a659621f0d0612572865fec1099a91e7622139acc3a1c689e7df1d96e81bf
+  metadata.gz: 38dd0ae99e1a1e21dd68963b5e6f85bb72d620955ab001df8136dc4d40122196d4bb88dd107bfe95fdd93bcb17befe907f4ebe001ad05f364067b17d40c839e3
+  data.tar.gz: be47e90cad90aefdd1ea96d494783731270b26c5a8f24843912eea6f418a1375bbbc7bdc3550181f763eef47eb46eb595d1e54fc2bc06ede1eb26abfbfeb917b

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## [v4.24.0](https://github.com/drwl/annotaterb/tree/v4.24.0) (2026-07-24)
+
+[Full Changelog](https://github.com/drwl/annotaterb/compare/v4.23.0...v4.24.0)
+
+**Implemented enhancements:**
+
+- Annotate postgres enums [\#309](https://github.com/drwl/annotaterb/issues/309)
+- `--frozen` option returns a non-zero error code when database is inaccessible [\#240](https://github.com/drwl/annotaterb/issues/240)
+- Add support for printing enum types [\#176](https://github.com/drwl/annotaterb/issues/176)
+
+**Fixed bugs:**
+
+- Annotation placement for namespaced models is inconsistent — anchor shifts with file shape \(doc comment presence\) [\#366](https://github.com/drwl/annotaterb/issues/366)
+- Fixture files that start with \<% \(erb\) insert doc inside the erb block [\#345](https://github.com/drwl/annotaterb/issues/345)
+- Schema information inserted every run into some fixture files. [\#344](https://github.com/drwl/annotaterb/issues/344)
+
+**Closed issues:**
+
+- Routes are not annotated after migration tasks [\#251](https://github.com/drwl/annotaterb/issues/251)
+
+**Merged pull requests:**
+
+- Bump version to v4.24.0 [\#371](https://github.com/drwl/annotaterb/pull/371) ([drwl](https://github.com/drwl))
+- Revert "Release v4.24.0" [\#370](https://github.com/drwl/annotaterb/pull/370) ([drwl](https://github.com/drwl))
+- Show DEFERRABLE INITIALLY on foreign keys [\#365](https://github.com/drwl/annotaterb/pull/365) ([kamipo](https://github.com/kamipo))
+- Annotate PostgreSQL unique and exclusion constraints [\#364](https://github.com/drwl/annotaterb/pull/364) ([kamipo](https://github.com/kamipo))
+- Fix `--without-comment` help text to say exclude [\#363](https://github.com/drwl/annotaterb/pull/363) ([OdenTakashi](https://github.com/OdenTakashi))
+- Fix NoMethodError when handling malformed annotations [\#362](https://github.com/drwl/annotaterb/pull/362) ([OdenTakashi](https://github.com/OdenTakashi))
+- Remove empty TODO comment from Runner [\#361](https://github.com/drwl/annotaterb/pull/361) ([OdenTakashi](https://github.com/OdenTakashi))
+- Move ignore\_database\_name check into AnnotationBuilder [\#360](https://github.com/drwl/annotaterb/pull/360) ([OdenTakashi](https://github.com/OdenTakashi))
+- Add YAML configuration option reference to the README. [\#359](https://github.com/drwl/annotaterb/pull/359) ([OdenTakashi](https://github.com/OdenTakashi))
+- Respect DB column defaults over `attribute :foo, default: X` overrides [\#358](https://github.com/drwl/annotaterb/pull/358) ([kamipo](https://github.com/kamipo))
+- added :ignore\_database\_name option [\#357](https://github.com/drwl/annotaterb/pull/357) ([HoneyryderChuck](https://github.com/HoneyryderChuck))
+- Add Markdown annotation idempotency test [\#356](https://github.com/drwl/annotaterb/pull/356) ([aouxwoux](https://github.com/aouxwoux))
+- Fix schema\_like? to recognize markdown-formatted annotation rows [\#354](https://github.com/drwl/annotaterb/pull/354) ([nashirox](https://github.com/nashirox))
+- Keep fixture annotations out of ERB blocks \(\#345\) [\#353](https://github.com/drwl/annotaterb/pull/353) ([Halvanhelv](https://github.com/Halvanhelv))
+- Stop tracking generated secondary DB artifacts in dummyapp [\#352](https://github.com/drwl/annotaterb/pull/352) ([OdenTakashi](https://github.com/OdenTakashi))
+- Add Rails version matrix to CI [\#351](https://github.com/drwl/annotaterb/pull/351) ([OdenTakashi](https://github.com/OdenTakashi))
+- Create release script [\#349](https://github.com/drwl/annotaterb/pull/349) ([drwl](https://github.com/drwl))
+- Generate changelog for v4.23.0 [\#348](https://github.com/drwl/annotaterb/pull/348) ([drwl](https://github.com/drwl))
+
 ## [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)

data/README.md

@@ -22,16 +22,17 @@ The schema comment looks like this:
 ```ruby
 # == Schema Information
 #
-# Table name: tasks
+# Table name: users
 #
-#  id         :integer          not null, primary key
-#  content    :string
-#  count      :integer
-#  status     :boolean
-#  created_at :datetime         not null
-#  updated_at :datetime         not null
+#  id            :integer          not null, primary key
+#  name          :string
+#  email         :string
+#  sign_in_count :integer          default(0), not null
+#  admin         :boolean          default(FALSE), not null
+#  created_at    :datetime         not null
+#  updated_at    :datetime         not null
 #
-class Task < ApplicationRecord
+class User < ApplicationRecord
   ...
 ```
 
@@ -68,7 +69,7 @@ This will copy a rake task into your Rails project's `lib/tasks` directory that
 $ bin/rails db:migrate
 # ...
 # Annotating models
-# Annotated (1): app/models/task.rb
+# Annotated (1): app/models/user.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.
@@ -158,6 +159,8 @@ Annotate model options:
         --without-column-comments    exclude column comments in model annotations
         --position-of-column-comment [with_name|rightmost_column]
                                      set the position, in the annotation block, of the column comment
+        --enum-default-format [label|raw|both]
+                                     set how defaults of enum backed columns are shown
         --with-table-comments        include table comments in model annotations
         --without-table-comments     exclude table comments in model annotations
         --classes-default-to-s class Custom classes to be represented with `to_s`, may be used multiple times
@@ -267,6 +270,7 @@ Keys use snake_case and match the gem defaults in `AnnotateRb::Options`. CLI fla
 | `simple_indexes` | `false` | Concat related indexes onto each column line. |
 | `show_check_constraints` | `false` | List check constraints. |
 | `show_enums` | `false` | Show PostgreSQL enum types. |
+| `enum_default_format` | `label` | Default shown for enum backed columns: `label` (`default("idnow")`), `raw` (`default(0)`) or `both` (`default(0: "idnow")`). |
 | `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). |

data/VERSION

@@ -1 +1 @@
-4.24.0
+4.25.0

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

@@ -37,6 +37,7 @@ module AnnotateRb
           when Float, Integer then value.to_s
           # BigDecimals need to be output in a non-normalized form and quoted.
           when BigDecimal then value.to_s("F")
+          when EnumDefault then "#{quote(value.raw)}: #{quote(value.label)}"
           when String then value.inspect
           else
             value.inspect

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ColumnAnnotation
+      # Pairs the raw DB default of an enum backed column with its label, so
+      # that annotations can show both.
+      EnumDefault = Struct.new(:raw, :label)
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/column_annotation.rb

@@ -8,6 +8,7 @@ module AnnotateRb
       autoload :ColumnWrapper, "annotate_rb/model_annotator/column_annotation/column_wrapper"
       autoload :AnnotationBuilder, "annotate_rb/model_annotator/column_annotation/annotation_builder"
       autoload :DefaultValueBuilder, "annotate_rb/model_annotator/column_annotation/default_value_builder"
+      autoload :EnumDefault, "annotate_rb/model_annotator/column_annotation/enum_default"
       autoload :ColumnComponent, "annotate_rb/model_annotator/column_annotation/column_component"
     end
   end

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

@@ -31,7 +31,7 @@ module AnnotateRb
         def parse_comments
           # Adds 0-indexed line numbers
           @input.split($/).each_with_index do |line, line_no|
-            if line.strip.starts_with?("#")
+            if line.strip.start_with?("#")
               @comments << [line, line_no]
             end
           end

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

@@ -13,7 +13,7 @@ module AnnotateRb
 
         def formatted_name
           @formatted_name ||= if foreign_key.name.blank?
-            foreign_key.column
+            stringified_columns
           else
             @options[:show_complete_foreign_keys] ? foreign_key.name : foreign_key.name.gsub(/(?<=^fk_rails_)[0-9a-f]{10}$/, "...")
           end

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

@@ -136,13 +136,23 @@ module AnnotateRb
 
         def columns_info
           Array(index.columns).map do |col|
-            if index.try(:orders) && index.orders[col.to_s]
-              "#{col} #{index.orders[col.to_s].upcase}"
-            else
-              col.to_s.gsub("\r", '\r').gsub("\n", '\n')
-            end
+            column = col.to_s.gsub("\r", '\r').gsub("\n", '\n')
+            opclass = column_option(:opclasses, col)
+            order = column_option(:orders, col)
+
+            [column, opclass, order&.upcase].compact.join(" ")
           end
         end
+
+        # ActiveRecord condenses per column index options (`opclasses`, `orders`)
+        # into a single value when every column shares the same one, so the
+        # option can either be a Hash keyed by column or a bare value.
+        def column_option(option, col)
+          value = index.try(option)
+          value = value[col.to_s] if value.is_a?(Hash)
+
+          value.presence&.to_s
+        end
       end
     end
   end

data/lib/annotate_rb/model_annotator/model_wrapper.rb

@@ -73,14 +73,17 @@ module AnnotateRb
       # `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.
+      # such as enum labels or `TimeZoneConverter` on datetime columns, we start
+      # from `column_defaults` and only substitute the DB schema value for
+      # attributes whose raw default was replaced.
       def 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
+          result[name] = if attribute_default_overridden?(name, column)
+            schema_default_for(column)
+          else
+            enum_default(name, column, value)
+          end
         end
       end
 
@@ -278,6 +281,33 @@ module AnnotateRb
 
       private
 
+      # `attribute :foo, default: X` replaces the raw default Rails read from
+      # the DB column, so comparing the two raw values detects the override.
+      # Comparing cast values instead would misreport decorated attribute types
+      # (an enum casts the DB default `0` into its label) as overrides.
+      def attribute_default_overridden?(name, column)
+        return false if column.nil?
+
+        @klass._default_attributes[name].value_before_type_cast != column.default
+      end
+
+      # An enum attribute type casts the raw DB default into its label, which is
+      # what `column_defaults` reports and what annotations have historically
+      # shown. `enum_default_format` picks between that label, the raw value,
+      # and both.
+      def enum_default(name, column, label)
+        return label unless @klass.defined_enums.key?(name)
+
+        raw = schema_default_for(column)
+        return label if raw == label
+
+        case @options[:enum_default_format]
+        when :raw then raw
+        when :both then ColumnAnnotation::EnumDefault.new(raw, label)
+        else label
+        end
+      end
+
       def schema_default_for(column)
         return nil if column.nil? || column.default.nil? || column.default_function
         cast_type_for(column).deserialize(column.default)

data/lib/annotate_rb/model_annotator/project_annotation_remover.rb

@@ -43,7 +43,9 @@ module AnnotateRb
 
         klass.reset_column_information
         model_name = klass.name.underscore
-        table_name = klass.table_name
+        # Match annotation behavior so a secondary model with a duplicate table
+        # name cannot remove annotations from the primary database's fixture.
+        table_name = klass.table_name if klass.connection_specification_name == ActiveRecord::Base.name
 
         model_instruction = SingleFileRemoveAnnotationInstruction.new(file, @options)
         instructions << model_instruction

data/lib/annotate_rb/model_annotator/related_files_list_builder.rb

@@ -88,8 +88,33 @@ module AnnotateRb
 
         patterns
           .map { |f| FileNameResolver.call(f, @model_name, @table_name) }
-          .map { |f| Dir.glob(f) }
-          .flatten
+          .flat_map { |f| Dir.glob(f) }
+          .select { |f| owning_root_dir(f) == model_root_dir }
+      end
+
+      def model_root_dir
+        return @model_root_dir if defined?(@model_root_dir)
+
+        @model_root_dir = owning_root_dir(@file)
+      end
+
+      # Patterns are expanded for every `root_dir` and resolved by model name alone, so models sharing a
+      #   file basename across root directories (e.g. packwerk packs) glob the same related files. Root
+      #   directories can be nested, so a file belongs to the most specific one containing it, and only
+      #   models from that same root directory may annotate it. Returns nil for the project root.
+      def owning_root_dir(file)
+        expanded_file = File.expand_path(file)
+
+        expanded_root_dirs
+          .select { |dir| expanded_file.start_with?("#{dir}/") }
+          .max_by(&:length)
+      end
+
+      def expanded_root_dirs
+        @expanded_root_dirs ||= Array(@options[:root_dir])
+          .reject { |root_dir| root_dir.to_s.empty? }
+          .flat_map { |root_dir| Dir.glob(root_dir) }
+          .map { |root_dir| File.expand_path(root_dir) }
       end
 
       def add_related_test_files

data/lib/annotate_rb/options.rb

@@ -63,7 +63,8 @@ module AnnotateRb
       with_comment: true, # ModelAnnotator
       with_column_comments: nil, # ModelAnnotator
       with_table_comments: nil, # ModelAnnotator
-      position_of_column_comment: :with_name # ModelAnnotator
+      position_of_column_comment: :with_name, # ModelAnnotator
+      enum_default_format: :label # ModelAnnotator
     }.freeze
 
     OTHER_OPTIONS = {
@@ -84,7 +85,6 @@ module AnnotateRb
       ignore_multi_database_name: false, # ModelAnnotator
       ignore_routes: nil, # RouteAnnotator
       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
@@ -141,7 +141,8 @@ module AnnotateRb
       :with_comment,
       :with_column_comments,
       :with_table_comments,
-      :position_of_column_comment
+      :position_of_column_comment,
+      :enum_default_format
     ].freeze
 
     OTHER_OPTION_KEYS = [
@@ -155,7 +156,6 @@ module AnnotateRb
       :ignore_routes,
       :ignore_multi_database_name,
       :models,
-      :routes,
       :skip_on_db_migrate,
       :auto_annotate_routes_after_migrate,
       :target_action,
@@ -224,6 +224,7 @@ module AnnotateRb
       @options[:with_column_comments] = @options[:with_comment] if @options[:with_column_comments].nil?
       @options[:with_table_comments] = @options[:with_comment] if @options[:with_table_comments].nil?
       @options[:position_of_column_comment] = @options[:position_of_column_comment].to_sym
+      @options[:enum_default_format] = @options[:enum_default_format].to_sym
 
       self
     end

data/lib/annotate_rb/parser.rb

@@ -268,6 +268,11 @@ module AnnotateRb
         @options[:position_of_column_comment] = value.to_sym
       end
 
+      option_parser.on("--enum-default-format [label|raw|both]",
+        "set how defaults of enum backed columns are shown") do |value|
+        @options[:enum_default_format] = value.to_sym
+      end
+
       option_parser.on("--with-table-comments",
         "include table comments in model annotations") do
         @options[:with_table_comments] = true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: annotaterb
 version: !ruby/object:Gem::Version
-  version: 4.24.0
+  version: 4.25.0
 platform: ruby
 authors:
 - Andrew W. Lee
@@ -88,6 +88,7 @@ files:
 - lib/annotate_rb/model_annotator/column_annotation/column_component.rb
 - lib/annotate_rb/model_annotator/column_annotation/column_wrapper.rb
 - lib/annotate_rb/model_annotator/column_annotation/default_value_builder.rb
+- lib/annotate_rb/model_annotator/column_annotation/enum_default.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