annotaterb 4.10.1 → 4.11.0

data/lib/annotate_rb/model_annotator/components.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    # Shared annotation components
+    module Components
+      class Base
+        # Methods default to #to_default, unless overridden by sub class
+        def to_markdown
+          to_default
+        end
+
+        def to_rdoc
+          to_default
+        end
+
+        def to_yard
+          to_default
+        end
+
+        def to_default
+          raise NoMethodError, "Not implemented by class #{self.class}"
+        end
+      end
+
+      class NilComponent < Base
+        # Used when we want to return a component, but does not affect annotation generation.
+        # It will get ignored when the consuming object calls Array#compact
+        def to_default
+          nil
+        end
+      end
+
+      class LineBreak < Base
+        def to_default
+          ""
+        end
+      end
+
+      class BlankCommentLine < Base
+        def to_default
+          "#"
+        end
+      end
+
+      class Header < Base
+        attr_reader :header
+
+        def initialize(header)
+          @header = header
+        end
+
+        def to_default
+          "# #{header}"
+        end
+
+        def to_markdown
+          "# ### #{header}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ForeignKeyAnnotation
+      class Annotation
+        HEADER_TEXT = "Foreign Keys"
+
+        def initialize(foreign_keys)
+          @foreign_keys = foreign_keys
+        end
+
+        def body
+          [
+            Components::BlankCommentLine.new,
+            Components::Header.new(HEADER_TEXT),
+            Components::BlankCommentLine.new,
+            *@foreign_keys
+          ]
+        end
+
+        def to_markdown
+          body.map(&:to_markdown).join("\n")
+        end
+
+        def to_default
+          body.map(&:to_default).join("\n")
+        end
+      end
+    end
+  end
+end

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

@@ -10,58 +10,26 @@ module AnnotateRb
         end
 
         def build
-          fk_info = if @options[:format_markdown]
-            "#\n# ### Foreign Keys\n#\n"
-          else
-            "#\n# Foreign Keys\n#\n"
-          end
-
-          return "" unless @model.connection.respond_to?(:supports_foreign_keys?) &&
+          return Components::NilComponent.new if !@options[:show_foreign_keys]
+          return Components::NilComponent.new unless @model.connection.respond_to?(:supports_foreign_keys?) &&
             @model.connection.supports_foreign_keys? && @model.connection.respond_to?(:foreign_keys)
 
           foreign_keys = @model.connection.foreign_keys(@model.table_name)
-          return "" if foreign_keys.empty?
-
-          format_name = lambda do |fk|
-            return fk.column if fk.name.blank?
+          return Components::NilComponent.new if foreign_keys.empty?
 
-            @options[:show_complete_foreign_keys] ? fk.name : fk.name.gsub(/(?<=^fk_rails_)[0-9a-f]{10}$/, "...")
+          fks = foreign_keys.map do |fk|
+            ForeignKeyComponentBuilder.new(fk, @options)
           end
 
-          max_size = foreign_keys.map(&format_name).map(&:size).max + 1
-          foreign_keys.sort_by { |fk| [format_name.call(fk), stringify_columns(fk.column)] }.each do |fk|
-            ref_info = if fk.column.is_a?(Array) # Composite foreign key using multiple columns
-              "#{stringify_columns(fk.column)} => #{fk.to_table}#{stringify_columns(fk.primary_key)}"
-            else
-              "#{fk.column} => #{fk.to_table}.#{fk.primary_key}"
-            end
+          max_size = fks.map(&:formatted_name).map(&:size).max + 1
 
-            constraints_info = ""
-            constraints_info += "ON DELETE => #{fk.on_delete} " if fk.on_delete
-            constraints_info += "ON UPDATE => #{fk.on_update} " if fk.on_update
-            constraints_info = constraints_info.strip
+          foreign_key_components = fks.sort_by { |fk| [fk.formatted_name, fk.stringified_columns] }.map do |fk|
+            # fk is a ForeignKeyComponentBuilder
 
-            fk_info += if @options[:format_markdown]
-              format("# * `%s`%s:\n#     * **`%s`**\n",
-                format_name.call(fk),
-                constraints_info.blank? ? "" : " (_#{constraints_info}_)",
-                ref_info)
-            else
-              format("#  %-#{max_size}.#{max_size}s %s %s",
-                format_name.call(fk),
-                "(#{ref_info})",
-                constraints_info).rstrip + "\n"
-            end
+            ForeignKeyComponent.new(fk.formatted_name, fk.constraints_info, fk.ref_info, max_size)
           end
 
-          fk_info
-        end
-
-        private
-
-        # The fk columns might be composite keys, so format them into a string for the annotation
-        def stringify_columns(columns)
-          columns.is_a?(Array) ? "[#{columns.join(", ")}]" : columns
+          _annotation = Annotation.new(foreign_key_components)
         end
       end
     end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ForeignKeyAnnotation
+      class ForeignKeyComponent < Components::Base
+        attr_reader :formatted_name, :constraints_info, :ref_info, :max_size
+
+        def initialize(formatted_name, constraints_info, ref_info, max_size)
+          @formatted_name = formatted_name
+          @constraints_info = constraints_info
+          @ref_info = ref_info
+          @max_size = max_size
+        end
+
+        def to_markdown
+          format("# * `%s`%s:\n#     * **`%s`**",
+            formatted_name,
+            constraints_info.blank? ? "" : " (_#{constraints_info}_)",
+            ref_info)
+        end
+
+        def to_default
+          # standard:disable Lint/FormatParameterMismatch
+          format("#  %-#{max_size}.#{max_size}s %s %s",
+            formatted_name,
+            "(#{ref_info})",
+            constraints_info).rstrip
+          # standard:enable Lint/FormatParameterMismatch
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ForeignKeyAnnotation
+      class ForeignKeyComponentBuilder
+        attr_reader :foreign_key
+
+        def initialize(foreign_key, options)
+          @foreign_key = foreign_key
+          @options = options
+        end
+
+        def formatted_name
+          @formatted_name ||= if foreign_key.name.blank?
+            foreign_key.column
+          else
+            @options[:show_complete_foreign_keys] ? foreign_key.name : foreign_key.name.gsub(/(?<=^fk_rails_)[0-9a-f]{10}$/, "...")
+          end
+        end
+
+        def stringified_columns
+          @stringified_columns ||= stringify(foreign_key.column)
+        end
+
+        def stringified_primary_key
+          @stringified_primary_key ||= stringify(foreign_key.primary_key)
+        end
+
+        def constraints_info
+          @constraints_info ||= begin
+            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
+            constraints_info.strip
+          end
+        end
+
+        def ref_info
+          if foreign_key.column.is_a?(Array) # Composite foreign key using multiple columns
+            "#{stringified_columns} => #{foreign_key.to_table}#{stringified_primary_key}"
+          else
+            "#{foreign_key.column} => #{foreign_key.to_table}.#{foreign_key.primary_key}"
+          end
+        end
+
+        private
+
+        # The fk columns or primary key might be composite (an Array), so format them into a string for the annotation
+        def stringify(columns)
+          columns.is_a?(Array) ? "[#{columns.join(", ")}]" : columns
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/foreign_key_annotation.rb

@@ -4,6 +4,9 @@ module AnnotateRb
   module ModelAnnotator
     module ForeignKeyAnnotation
       autoload :AnnotationBuilder, "annotate_rb/model_annotator/foreign_key_annotation/annotation_builder"
+      autoload :Annotation, "annotate_rb/model_annotator/foreign_key_annotation/annotation"
+      autoload :ForeignKeyComponent, "annotate_rb/model_annotator/foreign_key_annotation/foreign_key_component"
+      autoload :ForeignKeyComponentBuilder, "annotate_rb/model_annotator/foreign_key_annotation/foreign_key_component_builder"
     end
   end
 end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module IndexAnnotation
+      class Annotation
+        HEADER_TEXT = "Indexes"
+
+        def initialize(indexes)
+          @indexes = indexes
+        end
+
+        def body
+          [
+            Components::BlankCommentLine.new,
+            Components::Header.new(HEADER_TEXT),
+            Components::BlankCommentLine.new,
+            *@indexes
+          ]
+        end
+
+        def to_markdown
+          body.map(&:to_markdown).join("\n")
+        end
+
+        def to_default
+          body.map(&:to_default).join("\n")
+        end
+      end
+    end
+  end
+end

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

@@ -4,108 +4,24 @@ module AnnotateRb
   module ModelAnnotator
     module IndexAnnotation
       class AnnotationBuilder
-        INDEX_CLAUSES = {
-          unique: {
-            default: "UNIQUE",
-            markdown: "_unique_"
-          },
-          where: {
-            default: "WHERE",
-            markdown: "_where_"
-          },
-          using: {
-            default: "USING",
-            markdown: "_using_"
-          }
-        }.freeze
-
         def initialize(model, options)
           @model = model
           @options = options
         end
 
         def build
-          index_info = if @options[:format_markdown]
-            "#\n# ### Indexes\n#\n"
-          else
-            "#\n# Indexes\n#\n"
-          end
+          return Components::NilComponent.new if !@options[:show_indexes]
 
           indexes = @model.retrieve_indexes_from_table
-          return "" if indexes.empty?
+          return Components::NilComponent.new if indexes.empty?
 
-          max_size = indexes.collect { |index| index.name.size }.max + 1
-          indexes.sort_by(&:name).each do |index|
-            index_info += if @options[:format_markdown]
-              final_index_string_in_markdown(index)
-            else
-              final_index_string(index, max_size)
-            end
-          end
-
-          index_info
-        end
-
-        private
-
-        def index_using_info(index, format = :default)
-          value = index.try(:using) && index.using.try(:to_sym)
-          if !value.blank? && value != :btree
-            " #{INDEX_CLAUSES[:using][format]} #{value}"
-          else
-            ""
-          end
-        end
+          max_size = indexes.map { |index| index.name.size }.max + 1
 
-        def index_where_info(index, format = :default)
-          value = index.try(:where).try(:to_s)
-          if value.blank?
-            ""
-          else
-            " #{INDEX_CLAUSES[:where][format]} #{value}"
+          indexes = indexes.sort_by(&:name).map do |index|
+            IndexComponent.new(index, max_size)
           end
-        end
-
-        def index_unique_info(index, format = :default)
-          index.unique ? " #{INDEX_CLAUSES[:unique][format]}" : ""
-        end
 
-        def final_index_string_in_markdown(index)
-          details = format(
-            "%s%s%s",
-            index_unique_info(index, :markdown),
-            index_where_info(index, :markdown),
-            index_using_info(index, :markdown)
-          ).strip
-          details = " (#{details})" unless details.blank?
-
-          format(
-            "# * `%s`%s:\n#     * **`%s`**\n",
-            index.name,
-            details,
-            index_columns_info(index).join("`**\n#     * **`")
-          )
-        end
-
-        def final_index_string(index, max_size)
-          format(
-            "#  %-#{max_size}.#{max_size}s %s%s%s%s",
-            index.name,
-            "(#{index_columns_info(index).join(",")})",
-            index_unique_info(index),
-            index_where_info(index),
-            index_using_info(index)
-          ).rstrip + "\n"
-        end
-
-        def index_columns_info(index)
-          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
-          end
+          _annotation = Annotation.new(indexes)
         end
       end
     end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module IndexAnnotation
+      class IndexComponent < Components::Base
+        attr_reader :index, :max_size
+
+        def initialize(index, max_size)
+          @index = index
+          @max_size = max_size
+        end
+
+        def to_default
+          unique_info = index.unique ? " UNIQUE" : ""
+
+          value = index.try(:where).try(:to_s)
+          where_info = if value.present?
+            " WHERE #{value}"
+          else
+            ""
+          end
+
+          value = index.try(:using).try(:to_sym)
+          using_info = if value.present? && value != :btree
+            " USING #{value}"
+          else
+            ""
+          end
+
+          # standard:disable Lint/FormatParameterMismatch
+          sprintf(
+            "#  %-#{max_size}.#{max_size}s %s%s%s%s",
+            index.name,
+            "(#{columns_info.join(",")})",
+            unique_info,
+            where_info,
+            using_info
+          ).rstrip
+          # standard:enable Lint/FormatParameterMismatch
+        end
+
+        def to_markdown
+          unique_info = index.unique ? " _unique_" : ""
+
+          value = index.try(:where).try(:to_s)
+          where_info = if value.present?
+            " _where_ #{value}"
+          else
+            ""
+          end
+
+          value = index.try(:using).try(:to_sym)
+          using_info = if value.present? && value != :btree
+            " _using_ #{value}"
+          else
+            ""
+          end
+
+          details = sprintf(
+            "%s%s%s",
+            unique_info,
+            where_info,
+            using_info
+          ).strip
+          details = " (#{details})" unless details.blank?
+
+          sprintf(
+            "# * `%s`%s:\n#     * **`%s`**",
+            index.name,
+            details,
+            columns_info.join("`**\n#     * **`")
+          )
+        end
+
+        private
+
+        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
+          end
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/index_annotation.rb

@@ -4,6 +4,8 @@ module AnnotateRb
   module ModelAnnotator
     module IndexAnnotation
       autoload :AnnotationBuilder, "annotate_rb/model_annotator/index_annotation/annotation_builder"
+      autoload :IndexComponent, "annotate_rb/model_annotator/index_annotation/index_component"
+      autoload :Annotation, "annotate_rb/model_annotator/index_annotation/annotation"
     end
   end
 end

data/lib/annotate_rb/model_annotator/model_wrapper.rb

@@ -128,7 +128,12 @@ module AnnotateRb
       end
 
       def with_comments?
-        @with_comments ||= raw_columns.first.respond_to?(:comment) &&
+        return @with_comments if instance_variable_defined?(:@with_comments)
+
+        @with_comments =
+          @options[:with_comment] &&
+          @options[:with_column_comments] &&
+          raw_columns.first.respond_to?(:comment) &&
           raw_columns.map(&:comment).any? { |comment| !comment.nil? }
       end
 

data/lib/annotate_rb/model_annotator/project_annotator.rb

@@ -39,7 +39,7 @@ module AnnotateRb
         instructions = []
 
         klass.reset_column_information
-        annotation = AnnotationBuilder.new(klass, @options).build
+        annotation = Annotation::AnnotationBuilder.new(klass, @options).build
         model_name = klass.name.underscore
         table_name = klass.table_name
 

data/lib/annotate_rb/model_annotator.rb

@@ -28,5 +28,7 @@ module AnnotateRb
     autoload :ZeitwerkClassGetter, "annotate_rb/model_annotator/zeitwerk_class_getter"
     autoload :CheckConstraintAnnotation, "annotate_rb/model_annotator/check_constraint_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"
   end
 end

data/lib/annotate_rb/rake_bootstrapper.rb

@@ -4,30 +4,14 @@ module AnnotateRb
   class RakeBootstrapper
     class << self
       def call(options)
-        begin
-          require "rake/dsl_definition"
-        rescue => e
-          # We might just be on an old version of Rake...
-          warn e.message
-          exit e.status_code
-        end
-
         require "rake"
-        load "./Rakefile" if File.exist?("./Rakefile")
+        load "./Rakefile" if File.exist?("./Rakefile") && !Rake::Task.task_defined?(:environment)
 
         begin
           Rake::Task[:environment].invoke
         rescue
           nil
         end
-
-        unless defined?(Rails)
-          # Not in a Rails project, so time to load up the parts of
-          # ActiveSupport we need.
-          require "active_support"
-          require "active_support/core_ext/class/subclasses"
-          require "active_support/core_ext/string/inflections"
-        end
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: annotaterb
 version: !ruby/object:Gem::Version
-  version: 4.10.1
+  version: 4.11.0
 platform: ruby
 authors:
 - Andrew W. Lee
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-07 00:00:00.000000000 Z
+date: 2024-08-16 00:00:00.000000000 Z
 dependencies: []
 description: Annotates Rails/ActiveRecord Models, routes, fixtures, and others based
   on the database schema.
@@ -40,20 +40,29 @@ files:
 - lib/annotate_rb/model_annotator/annotated_file.rb
 - lib/annotate_rb/model_annotator/annotated_file/generator.rb
 - lib/annotate_rb/model_annotator/annotated_file/updater.rb
-- lib/annotate_rb/model_annotator/annotation_builder.rb
+- lib/annotate_rb/model_annotator/annotation.rb
+- lib/annotate_rb/model_annotator/annotation/annotation_builder.rb
+- lib/annotate_rb/model_annotator/annotation/main_header.rb
+- lib/annotate_rb/model_annotator/annotation/markdown_header.rb
+- lib/annotate_rb/model_annotator/annotation/schema_footer.rb
+- lib/annotate_rb/model_annotator/annotation/schema_header.rb
 - lib/annotate_rb/model_annotator/annotation_decider.rb
 - lib/annotate_rb/model_annotator/annotation_diff.rb
 - lib/annotate_rb/model_annotator/annotation_diff_generator.rb
 - lib/annotate_rb/model_annotator/annotator.rb
 - lib/annotate_rb/model_annotator/bad_model_file_error.rb
 - lib/annotate_rb/model_annotator/check_constraint_annotation.rb
+- lib/annotate_rb/model_annotator/check_constraint_annotation/annotation.rb
 - lib/annotate_rb/model_annotator/check_constraint_annotation/annotation_builder.rb
+- lib/annotate_rb/model_annotator/check_constraint_annotation/check_constraint_component.rb
 - lib/annotate_rb/model_annotator/column_annotation.rb
 - lib/annotate_rb/model_annotator/column_annotation/annotation_builder.rb
 - lib/annotate_rb/model_annotator/column_annotation/attributes_builder.rb
+- 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/type_builder.rb
+- lib/annotate_rb/model_annotator/components.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
@@ -63,9 +72,14 @@ files:
 - lib/annotate_rb/model_annotator/file_parser/yml_parser.rb
 - lib/annotate_rb/model_annotator/file_to_parser_mapper.rb
 - lib/annotate_rb/model_annotator/foreign_key_annotation.rb
+- lib/annotate_rb/model_annotator/foreign_key_annotation/annotation.rb
 - lib/annotate_rb/model_annotator/foreign_key_annotation/annotation_builder.rb
+- lib/annotate_rb/model_annotator/foreign_key_annotation/foreign_key_component.rb
+- lib/annotate_rb/model_annotator/foreign_key_annotation/foreign_key_component_builder.rb
 - lib/annotate_rb/model_annotator/index_annotation.rb
+- lib/annotate_rb/model_annotator/index_annotation/annotation.rb
 - lib/annotate_rb/model_annotator/index_annotation/annotation_builder.rb
+- lib/annotate_rb/model_annotator/index_annotation/index_component.rb
 - lib/annotate_rb/model_annotator/model_class_getter.rb
 - lib/annotate_rb/model_annotator/model_files_getter.rb
 - lib/annotate_rb/model_annotator/model_wrapper.rb
@@ -122,7 +136,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: A gem for generating annotations for Rails projects.