annotaterb 4.22.0 → 4.24.0

data/lib/annotate_rb/model_annotator/project_annotator.rb

@@ -42,13 +42,14 @@ module AnnotateRb
         klass.reset_column_information
         annotation = Annotation::AnnotationBuilder.new(klass, @options).build
         model_name = klass.name.underscore
+        model_class_name = klass.name.demodulize
 
         # In multi-database configurations, it is possible for different models to have the same table name but live
         #   in different databases. Here we are opting to use the table name to find related files only when the model
         #   is using the primary connection.
         table_name = klass.table_name if klass.connection_specification_name == ActiveRecord::Base.name
 
-        model_instruction = SingleFileAnnotatorInstruction.new(file, annotation, :position_in_class, @options)
+        model_instruction = SingleFileAnnotatorInstruction.new(file, annotation, :position_in_class, @options, model_class_name: model_class_name)
         instructions << model_instruction
 
         related_files = RelatedFilesListBuilder.new(file, model_name, table_name, @options).build

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

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

data/lib/annotate_rb/model_annotator/single_file_annotator_instruction.rb

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

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

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

data/lib/annotate_rb/model_annotator.rb

@@ -27,6 +27,9 @@ 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"
     autoload :Annotation, "annotate_rb/model_annotator/annotation"

data/lib/annotate_rb/options.rb

@@ -42,13 +42,18 @@ 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
+      show_indexes_comments: false, # ModelAnnotator
       show_indexes_include: false, # ModelAnnotator
       show_virtual_columns: false, # ModelAnnotator
       simple_indexes: false, # ModelAnnotator
@@ -78,10 +83,10 @@ module AnnotateRb
       ignore_columns: nil, # ModelAnnotator
       ignore_multi_database_name: false, # ModelAnnotator
       ignore_routes: nil, # RouteAnnotator
-      ignore_unknown_models: false, # ModelAnnotator
       models: true, # Core
       routes: false, # Core
       skip_on_db_migrate: false, # Core
+      auto_annotate_routes_after_migrate: false, # Core
       target_action: :do_annotations, # Core; Possible values: :do_annotations, :remove_annotations
       wrapper: nil, # ModelAnnotator, RouteAnnotator
       wrapper_close: nil, # ModelAnnotator, RouteAnnotator
@@ -116,13 +121,18 @@ 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,
       :show_indexes,
+      :show_indexes_comments,
       :show_indexes_include,
       :simple_indexes,
       :sort,
@@ -143,11 +153,11 @@ module AnnotateRb
       :timestamp_columns,
       :ignore_columns,
       :ignore_routes,
-      :ignore_unknown_models,
       :ignore_multi_database_name,
       :models,
       :routes,
       :skip_on_db_migrate,
+      :auto_annotate_routes_after_migrate,
       :target_action,
       :wrapper,
       :wrapper_close,

data/lib/annotate_rb/parser.rb

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

data/lib/annotate_rb/route_annotator/base_processor.rb

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

data/lib/annotate_rb/route_annotator/helper.rb

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

data/lib/annotate_rb/runner.rb

@@ -5,10 +5,18 @@ module AnnotateRb
     class << self
       attr_reader :runner
 
-      def run(args)
+      def run_after_migration
+        config_file_options = ConfigLoader.load_config
+        options = Options.from(config_file_options)
+
+        commands = ["models", *(options[:auto_annotate_routes_after_migrate] ? ["routes"] : [])]
+        commands.each { |cmd| run([cmd], config_file_options: config_file_options) }
+      end
+
+      def run(args, config_file_options: nil)
         self.runner = new
 
-        runner.run(args)
+        runner.run(args, config_file_options: config_file_options)
 
         self.runner = nil
       end
@@ -22,14 +30,14 @@ module AnnotateRb
       attr_writer :runner
     end
 
-    def run(args)
+    def run(args, config_file_options: nil)
       parser = Parser.new(args, {})
 
       parsed_options = parser.parse
       remaining_args = parser.remaining_args
 
       AnnotateRb::ConfigFinder.config_path = parsed_options[:config_path] if parsed_options[:config_path]
-      config_file_options = ConfigLoader.load_config
+      config_file_options = ConfigLoader.load_config if config_file_options.nil?
       options = config_file_options.merge(parsed_options)
 
       @options = Options.from(options, {working_args: remaining_args})
@@ -38,8 +46,6 @@ module AnnotateRb
       raise "Didn't specify a command" unless @options[:command]
 
       @options[:command].call(@options)
-
-      # TODO
     end
   end
 end

data/lib/annotate_rb/tasks/annotate_models_migrate.rake

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

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

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

metadata

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