annotaterb 4.22.0 → 4.24.0

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

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

data/lib/annotate_rb/model_annotator/enum_annotation.rb

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

data/lib/annotate_rb/model_annotator/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

@@ -8,6 +8,30 @@ module AnnotateRb
         COMPAT_PREFIX_MD = "## Schema Info"
         DEFAULT_ANNOTATION_ENDING = "#"
 
+        SCHEMA_HEADER_PREFIXES = [
+          COMPAT_PREFIX,
+          COMPAT_PREFIX_MD,
+          "Table name:",
+          "Database name:",
+          "Schema version:"
+        ].freeze
+
+        SCHEMA_HEADER_EXACT = [
+          IndexAnnotation::Annotation::HEADER_TEXT,
+          ForeignKeyAnnotation::Annotation::HEADER_TEXT,
+          CheckConstraintAnnotation::Annotation::HEADER_TEXT,
+          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
@@ -70,10 +94,7 @@ module AnnotateRb
               end
             end
           else
-            # Walk back until we find the end of the annotation comment block
-            while ending > start && comments[ending].first != DEFAULT_ANNOTATION_ENDING
-              ending -= 1
-            end
+            ending = walk_forward_through_schema(comments, start, ending)
           end
 
           # We want .last because we want the line indexes
@@ -95,6 +116,56 @@ module AnnotateRb
         def annotated?
           @annotation_start && @annotation_end
         end
+
+        private
+
+        def walk_forward_through_schema(comments, start, block_end)
+          ending = start
+          while ending < block_end
+            break unless schema_like?(comments[ending + 1].first)
+            ending += 1
+          end
+          ending
+        end
+
+        # 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
+
+          text = comment.sub(/\A#\s?/, "")
+          return false if text.empty?
+
+          return true if SCHEMA_HEADER_PREFIXES.any? { |p| text.start_with?(p) }
+          return true if SCHEMA_HEADER_EXACT.include?(text)
+
+          # 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
     end
   end

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

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

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

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

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

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

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

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

data/lib/annotate_rb/model_annotator/file_parser/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/file_parser.rb

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

data/lib/annotate_rb/model_annotator/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/index_annotation/index_component.rb

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

data/lib/annotate_rb/model_annotator/model_wrapper.rb

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