annotaterb 4.1.0 → 4.2.0

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ColumnAnnotation
+      class AnnotationBuilder
+        BARE_TYPE_ALLOWANCE = 16
+        MD_TYPE_ALLOWANCE = 18
+
+        def initialize(column, model, max_size, options)
+          @column = column
+          @model = model
+          @max_size = max_size
+          @options = options
+        end
+
+        def build
+          result = ""
+
+          is_primary_key = is_column_primary_key?(@model, @column.name)
+
+          table_indices = @model.retrieve_indexes_from_table
+          column_indices = table_indices.select { |ind| ind.columns.include?(@column.name) }
+
+          column_attributes = AttributesBuilder.new(@column, @options, is_primary_key, column_indices).build
+          formatted_column_type = TypeBuilder.new(@column, @options).build
+
+          col_name = if @model.with_comments? && @column.comment
+            "#{@column.name}(#{@column.comment.gsub(/\n/, '\\n')})"
+          else
+            @column.name
+          end
+
+          result += if @options[:format_rdoc]
+            format_rdoc(col_name, @max_size, formatted_column_type, column_attributes)
+          elsif @options[:format_yard]
+            format_yard(col_name, @max_size, formatted_column_type, column_attributes)
+          elsif @options[:format_markdown]
+            format_markdown(col_name, @max_size, formatted_column_type, column_attributes)
+          else
+            format_default(col_name, @max_size, formatted_column_type, column_attributes)
+          end
+
+          result
+        end
+
+        private
+
+        def non_ascii_length(string)
+          string.to_s.chars.count { |element| !element.ascii_only? }
+        end
+
+        def mb_chars_ljust(string, length)
+          string = string.to_s
+          padding = length - Helper.width(string)
+          if padding.positive?
+            string + (" " * padding)
+          else
+            string[0..(length - 1)]
+          end
+        end
+
+        def map_col_type_to_ruby_classes(col_type)
+          case col_type
+          when "integer" then Integer.to_s
+          when "float" then Float.to_s
+          when "decimal" then BigDecimal.to_s
+          when "datetime", "timestamp", "time" then Time.to_s
+          when "date" then Date.to_s
+          when "text", "string", "binary", "inet", "uuid" then String.to_s
+          when "json", "jsonb" then Hash.to_s
+          when "boolean" then "Boolean"
+          end
+        end
+
+        def format_rdoc(col_name, max_size, formatted_column_type, column_attributes)
+          format("# %-#{max_size}.#{max_size}s<tt>%s</tt>",
+            "*#{col_name}*::",
+            column_attributes.unshift(formatted_column_type).join(", ")).rstrip + "\n"
+        end
+
+        def format_yard(col_name, _max_size, formatted_column_type, _column_attributes)
+          res = ""
+          res += sprintf("# @!attribute #{col_name}") + "\n"
+
+          ruby_class = if @column.respond_to?(:array) && @column.array
+            "Array<#{map_col_type_to_ruby_classes(formatted_column_type)}>"
+          else
+            map_col_type_to_ruby_classes(formatted_column_type)
+          end
+
+          res += sprintf("#   @return [#{ruby_class}]") + "\n"
+
+          res
+        end
+
+        def format_markdown(col_name, max_size, formatted_column_type, column_attributes)
+          name_remainder = max_size - col_name.length - non_ascii_length(col_name)
+          type_remainder = (MD_TYPE_ALLOWANCE - 2) - formatted_column_type.length
+
+          format("# **`%s`**%#{name_remainder}s | `%s`%#{type_remainder}s | `%s`",
+            col_name,
+            " ",
+            formatted_column_type,
+            " ",
+            column_attributes.join(", ").rstrip).gsub("``", "  ").rstrip + "\n"
+        end
+
+        def format_default(col_name, max_size, formatted_column_type, column_attributes)
+          format("#  %s:%s %s",
+            mb_chars_ljust(col_name, max_size),
+            mb_chars_ljust(formatted_column_type, BARE_TYPE_ALLOWANCE),
+            column_attributes.join(", ")).rstrip + "\n"
+        end
+
+        # TODO: Simplify this conditional
+        def is_column_primary_key?(model, column_name)
+          if model.primary_key
+            if model.primary_key.is_a?(Array)
+              # If the model has multiple primary keys, check if this column is one of them
+              if model.primary_key.collect(&:to_sym).include?(column_name.to_sym)
+                return true
+              end
+            elsif column_name.to_sym == model.primary_key.to_sym
+              # If model has 1 primary key, check if this column is it
+              return true
+            end
+          end
+
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ColumnAnnotation
+      class AttributesBuilder
+        # Don't show default value for these column types
+        NO_DEFAULT_COL_TYPES = %w[json jsonb hstore].freeze
+
+        def initialize(column, options, is_primary_key, column_indices)
+          @column = ColumnWrapper.new(column)
+          @options = options
+          @is_primary_key = is_primary_key
+          @column_indices = column_indices
+        end
+
+        # Get the list of attributes that should be included in the annotation for
+        # a given column.
+        def build
+          column_type = @column.column_type_string
+          attrs = []
+
+          unless @column.default.nil? || hide_default?
+            schema_default = "default(#{@column.default_string})"
+
+            attrs << schema_default
+          end
+
+          if @column.unsigned?
+            attrs << "unsigned"
+          end
+
+          if !@column.null
+            attrs << "not null"
+          end
+
+          if @is_primary_key
+            attrs << "primary key"
+          end
+
+          is_special_type = %w[spatial geometry geography].include?(column_type)
+          is_decimal_type = column_type == "decimal"
+
+          if !is_decimal_type && !is_special_type
+            if @column.limit && !@options[:format_yard]
+              if @column.limit.is_a?(Array)
+                attrs << "(#{@column.limit.join(", ")})"
+              end
+            end
+          end
+
+          # Check out if we got an array column
+          if @column.array?
+            attrs << "is an Array"
+          end
+
+          # Check out if we got a geometric column
+          # and print the type and SRID
+          if @column.geometry_type?
+            attrs << "#{@column.geometry_type}, #{@column.srid}"
+          elsif @column.geometric_type? && @column.geometric_type.present?
+            attrs << "#{@column.geometric_type.to_s.downcase}, #{@column.srid}"
+          end
+
+          # Check if the column has indices and print "indexed" if true
+          # If the index includes another column, print it too.
+          if @options[:simple_indexes]
+            # Note: there used to be a klass.table_exists? call here, but removed it as it seemed unnecessary.
+
+            sorted_column_indices&.each do |index|
+              indexed_columns = index.columns.reject { |i| i == @column.name }
+
+              attrs << if indexed_columns.empty?
+                "indexed"
+              else
+                "indexed => [#{indexed_columns.join(", ")}]"
+              end
+            end
+          end
+
+          attrs
+        end
+
+        def sorted_column_indices
+          # Not sure why there were & safe accessors here, but keeping in for time being.
+          sorted_indices = @column_indices&.sort_by(&:name)
+
+          _sorted_indices = sorted_indices.reject { |ind| ind.columns.is_a?(String) }
+        end
+
+        def hide_default?
+          excludes =
+            if @options[:hide_default_column_types].blank?
+              NO_DEFAULT_COL_TYPES
+            else
+              @options[:hide_default_column_types].split(",")
+            end
+
+          excludes.include?(@column.column_type_string)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ColumnAnnotation
+      class ColumnWrapper
+        def initialize(column)
+          @column = column
+        end
+
+        def default
+          # Note: Used to be klass.column_defaults[name], where name is the column name.
+          # Looks to be identical, but keeping note here in case there are differences.
+          _column_default = @column.default
+        end
+
+        def default_string
+          quote(@column.default)
+        end
+
+        def type
+          @column.type
+        end
+
+        def column_type_string
+          if (@column.respond_to?(:bigint?) && @column.bigint?) || /\Abigint\b/ =~ @column.sql_type
+            "bigint"
+          else
+            (@column.type || @column.sql_type).to_s
+          end
+        end
+
+        def unsigned?
+          @column.respond_to?(:unsigned?) && @column.unsigned?
+        end
+
+        def null
+          @column.null
+        end
+
+        def precision
+          @column.precision
+        end
+
+        def scale
+          @column.scale
+        end
+
+        def limit
+          @column.limit
+        end
+
+        def geometry_type?
+          @column.respond_to?(:geometry_type)
+        end
+
+        def geometry_type
+          # TODO: Check if we need to check if it responds before accessing the geometry type
+          @column.geometry_type
+        end
+
+        def geometric_type?
+          @column.respond_to?(:geometric_type)
+        end
+
+        def geometric_type
+          # TODO: Check if we need to check if it responds before accessing the geometric type
+          @column.geometric_type
+        end
+
+        def srid
+          # TODO: Check if we need to check if it responds before accessing the srid
+          @column.srid
+        end
+
+        def array?
+          @column.respond_to?(:array) && @column.array
+        end
+
+        def name
+          @column.name
+        end
+
+        private
+
+        # Simple quoting for the default column value
+        def quote(value)
+          case value
+          when NilClass then "NULL"
+          when TrueClass then "TRUE"
+          when FalseClass then "FALSE"
+          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 Array then value.map { |v| quote(v) }
+          else
+            value.inspect
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ColumnAnnotation
+      class TypeBuilder
+        # Don't show limit (#) on these column types
+        # Example: show "integer" instead of "integer(4)"
+        NO_LIMIT_COL_TYPES = %w[integer bigint boolean].freeze
+
+        def initialize(column, options)
+          @column = ColumnWrapper.new(column)
+          @options = options
+        end
+
+        # Returns the formatted column type as a string.
+        def build
+          column_type = @column.column_type_string
+
+          formatted_column_type = column_type
+
+          is_special_type = %w[spatial geometry geography].include?(column_type)
+          is_decimal_type = column_type == "decimal"
+
+          if is_decimal_type
+            formatted_column_type = "decimal(#{@column.precision}, #{@column.scale})"
+          elsif is_special_type
+            # Do nothing. Kept as a code fragment in case we need to do something here.
+          elsif @column.limit && !@options[:format_yard]
+            # Unsure if Column#limit will ever be an array. May be safe to remove.
+            if !@column.limit.is_a?(Array) && !hide_limit?
+              formatted_column_type = column_type + "(#{@column.limit})"
+            end
+          end
+
+          formatted_column_type
+        end
+
+        private
+
+        def hide_limit?
+          excludes =
+            if @options[:hide_limit_column_types].blank?
+              NO_LIMIT_COL_TYPES
+            else
+              @options[:hide_limit_column_types].split(",")
+            end
+
+          excludes.include?(@column.column_type_string)
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/column_annotation.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ColumnAnnotation
+      autoload :AttributesBuilder, "annotate_rb/model_annotator/column_annotation/attributes_builder"
+      autoload :TypeBuilder, "annotate_rb/model_annotator/column_annotation/type_builder"
+      autoload :ColumnWrapper, "annotate_rb/model_annotator/column_annotation/column_wrapper"
+      autoload :AnnotationBuilder, "annotate_rb/model_annotator/column_annotation/annotation_builder"
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/file_builder.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    # Generates the text file content with annotations, these are then to be written to filesystem.
+    class FileBuilder
+      def initialize(file_components, new_annotations, annotation_position, options)
+        @file_components = file_components
+        @new_annotations = new_annotations
+        @annotation_position = annotation_position
+        @options = options
+
+        @new_wrapped_annotations = wrapped_content(new_annotations)
+      end
+
+      def generate_content_with_new_annotations
+        # Need to keep `.to_s` for now since the it can be either a String or Symbol
+        annotation_write_position = @options[@annotation_position].to_s
+
+        _content = if %w[after bottom].include?(annotation_write_position)
+          @file_components.magic_comments + (@file_components.pure_file_content.rstrip + "\n\n" + @new_wrapped_annotations)
+        elsif @file_components.magic_comments.empty?
+          @file_components.magic_comments + @new_wrapped_annotations + @file_components.pure_file_content.lstrip
+        else
+          @file_components.magic_comments + "\n" + @new_wrapped_annotations + @file_components.pure_file_content.lstrip
+        end
+      end
+
+      def update_existing_annotations
+        return "" if !@file_components.has_annotations?
+
+        annotation_pattern = AnnotationPatternGenerator.call(@options)
+
+        new_annotation = @file_components.space_before_annotation + @new_wrapped_annotations + @file_components.space_after_annotation
+
+        _content = @file_components.current_file_content.sub(annotation_pattern, new_annotation)
+      end
+
+      private
+
+      def wrapped_content(content)
+        wrapper_open = if @options[:wrapper_open]
+          "# #{@options[:wrapper_open]}\n"
+        else
+          ""
+        end
+
+        wrapper_close = if @options[:wrapper_close]
+          "# #{@options[:wrapper_close]}\n"
+        else
+          ""
+        end
+
+        _wrapped_info_block = "#{wrapper_open}#{content}#{wrapper_close}"
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/file_components.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class FileComponents
+      SKIP_ANNOTATION_STRING = "# -*- SkipSchemaAnnotations"
+      SOME_PATTERN = /\A(?<start>\s*).*?\n(?<end>\s*)\z/m # Unsure what this pattern is
+
+      def initialize(file_content, new_annotations, options)
+        @file_content = file_content
+        @diff = AnnotationDiffGenerator.new(file_content, new_annotations).generate
+        @options = options
+        @annotation_pattern = AnnotationPatternGenerator.call(options)
+      end
+
+      def current_file_content
+        @file_content
+      end
+
+      # TODO: Rename method once it's clear what this actually does
+      def space_before_annotation
+        return @space_before_annotation if defined?(@space_before_annotation)
+
+        match = current_annotations.match(SOME_PATTERN)
+        @space_before_annotation = if match
+          match[:start]
+        end
+      end
+
+      # TODO: Rename method once it's clear what this actually does
+      def space_after_annotation
+        return @space_after_annotation if defined?(@space_after_annotation)
+
+        match = current_annotations.match(SOME_PATTERN)
+        @space_after_annotation = if match
+          match[:end]
+        end
+      end
+
+      def pure_file_content
+        @pure_file_content ||=
+          begin
+            content_without_magic_comments = @file_content.gsub(MagicCommentParser::MAGIC_COMMENTS_REGEX, "")
+            content_without_annotations = content_without_magic_comments.sub(@annotation_pattern, "")
+
+            content_without_annotations
+          end
+      end
+
+      def magic_comments
+        @magic_comments ||= MagicCommentParser.call(@file_content)
+      end
+
+      def has_skip_string?
+        @has_skip_string ||= @file_content.include?(SKIP_ANNOTATION_STRING)
+      end
+
+      def has_annotations?
+        @has_annotations ||= @diff.current_columns.present?
+      end
+
+      def annotations_changed?
+        @has_annotations_changed ||= @diff.changed?
+      end
+
+      def current_annotations
+        @current_annotations ||=
+          if has_annotations?
+            # `#has_annotations?` uses a different regex pattern than the one in `@annotation_pattern`,
+            # this could lead to unexpected behavior
+            @file_content.match(@annotation_pattern).to_s
+          else
+            ""
+          end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/file_name_resolver.rb

@@ -6,9 +6,9 @@ module AnnotateRb
       class << self
         def call(filename_template, model_name, table_name)
           filename_template
-            .gsub('%MODEL_NAME%', model_name)
-            .gsub('%PLURALIZED_MODEL_NAME%', model_name.pluralize)
-            .gsub('%TABLE_NAME%', table_name || model_name.pluralize)
+            .gsub("%MODEL_NAME%", model_name)
+            .gsub("%PLURALIZED_MODEL_NAME%", model_name.pluralize)
+            .gsub("%TABLE_NAME%", table_name || model_name.pluralize)
         end
       end
     end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ForeignKeyAnnotation
+      class AnnotationBuilder
+        def initialize(model, options)
+          @model = model
+          @options = options
+        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?) &&
+            @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.options[:column] if fk.name.blank?
+
+            @options[:show_complete_foreign_keys] ? fk.name : fk.name.gsub(/(?<=^fk_rails_)[0-9a-f]{10}$/, "...")
+          end
+
+          max_size = foreign_keys.map(&format_name).map(&:size).max + 1
+          foreign_keys.sort_by { |fk| [format_name.call(fk), fk.column] }.each do |fk|
+            ref_info = "#{fk.column} => #{fk.to_table}.#{fk.primary_key}"
+            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
+
+            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
+          end
+
+          fk_info
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/foreign_key_annotation.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module ForeignKeyAnnotation
+      autoload :AnnotationBuilder, "annotate_rb/model_annotator/foreign_key_annotation/annotation_builder"
+    end
+  end
+end