annotaterb 4.0.0 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af9f792c5cb7386482abff5b7fb151dd000785316e0849139795ce473d48d076
-  data.tar.gz: 3d96f0869c4fa6616570bd1e9d077c962e56f59be4437496fc0cd0e428b5f3e3
+  metadata.gz: 8888511eb71e6d0c45eadf9f562767868adf7cb9f2c5c58d6eb3458a65dfdc31
+  data.tar.gz: 51d25d56e5068979a09d4562e7018b0272f8f73e952941a4f66faece7408cc11
 SHA512:
-  metadata.gz: 8cf8cb1fe5183a9f814272173f8af849499789790a87c63fa15de25a561c249490c7fefc8605c69464298923c14d6349d29ece493ab35c22e37466a0707e27b1
-  data.tar.gz: 0e43bbc446a18dd28c08c68bda96e3acfe58b427e3d5d16f0836a713456629280dcc9eb67781013e1bf5a8c621cb3068b8e2058fb82267cc3a6e115805f64fad
+  metadata.gz: 9b878bfc48836e52fe762c547870b67619427772e54efd28835e8699371dc60fdb5511649d9f2bf39431541a9b07f8e32188469526dd109553f71badedd6ec45
+  data.tar.gz: df69b71c4c10cc046ebd6cf0a21391262b90e0bcffe19556b59214d7658623fa323a7adbf24e711726bb685377e47596d9b95fed9c2425f22f4877264eed97d8

data/README.md

@@ -60,10 +60,7 @@ $ bin/rails g annotate_rb:install
 This will copy a rake task into your Rails project's `lib/tasks` directory that will hook into the Rails project rake tasks, automatically running AnnotateRb after database migration rake tasks.
 
 ## Migrating from the annotate gem
-The old [annotate gem](https://github.com/ctran/annotate_models) relied on environment variables and hardcoded values in rake files for configuration. AnnotateRb is different. It reads from an optional configuration yml file and options from the CLI to function.
-
-* Remove the following files `lib/tasks/annotate_models.rake`, `lib/tasks/annotate_models_migrate.rake`, `lib/tasks/annotate_routes.rake`.
-* Run the generator install command above.
+Refer to the [migration guide](MIGRATION_GUIDE.md).
 
 ## Usage
 
@@ -160,7 +157,9 @@ Previously in the [Annotate](https://github.com/ctran/annotate_models) you could
 position: after
 ```
 
-Annotaterb reads first from the configuration file, if it exists, then merges it with any options passed into the CLI.
+Annotaterb reads first from the configuration file, if it exists, then merges it with any options passed into the CLI. 
+
+For further details visit the [section in the migration guide](MIGRATION_GUIDE.md#automatic-annotations-after-running-database-migration-commands).
 
 ### How to skip annotating a particular model
 If you want to always skip annotations on a particular model, add this string

data/VERSION

@@ -1 +1 @@
-4.0.0
+4.1.1

data/lib/annotate_rb/model_annotator/annotation_decider.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    # Class that encapsulates the logic to decide whether to annotate a model file and its related files or not.
+    class AnnotationDecider
+      def initialize(file, options)
+        @file = file
+        @options = options
+      end
+
+      def annotate?
+        return false if file_contains_skip_annotation
+
+        begin
+          klass = ModelClassGetter.call(@file, @options)
+
+          klass_is_a_class = klass.is_a?(Class)
+          klass_inherits_active_record_base = klass < ActiveRecord::Base
+          klass_is_not_abstract = klass.respond_to?(:abstract_class) && !klass.abstract_class?
+          klass_table_exists = klass.respond_to?(:abstract_class) && klass.table_exists?
+
+          not_sure_this_conditional = (!@options[:exclude_sti_subclasses] || !(klass.superclass < ActiveRecord::Base && klass.table_name == klass.superclass.table_name))
+
+          annotate_conditions = [
+            klass_is_a_class,
+            klass_inherits_active_record_base,
+            not_sure_this_conditional,
+            klass_is_not_abstract,
+            klass_table_exists
+          ]
+
+          to_annotate = annotate_conditions.all?
+
+          return to_annotate
+        rescue BadModelFileError => e
+          unless @options[:ignore_unknown_models]
+            $stderr.puts "Unable to annotate #{@file}: #{e.message}"
+            $stderr.puts "\t" + e.backtrace.join("\n\t") if @options[:trace]
+          end
+        rescue StandardError => e
+          $stderr.puts "Unable to annotate #{@file}: #{e.message}"
+          $stderr.puts "\t" + e.backtrace.join("\n\t") if @options[:trace]
+        end
+
+        false
+      end
+
+      private
+
+      def file_contains_skip_annotation
+        file_string = File.exist?(@file) ? File.read(@file) : ''
+
+        if /#{Constants::SKIP_ANNOTATION_PREFIX}.*/ =~ file_string
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/annotation_diff.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    # Plain old Ruby object for holding the differences
+    class AnnotationDiff
+      attr_reader :current_columns, :new_columns
+
+      def initialize(current_columns, new_columns)
+        @current_columns = current_columns.dup.freeze
+        @new_columns = new_columns.dup.freeze
+      end
+
+      def changed?
+        @changed ||= @current_columns != @new_columns
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/annotation_diff_generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    # Compares the current file content and new annotation block and generates the column annotation differences
+    class AnnotationDiffGenerator
+      HEADER_PATTERN = /(^# Table name:.*?\n(#.*[\r]?\n)*[\r]?)/.freeze
+      COLUMN_PATTERN = /^#[\t ]+[\w\*\.`\[\]():]+[\t ]+.+$/.freeze
+
+      class << self
+        def call(file_content, annotation_block)
+          new(file_content, annotation_block).generate
+        end
+      end
+
+      # @param [String] file_content The current file content of the model file we intend to annotate
+      # @param [String] annotation_block The annotation block we intend to write to the model file
+      def initialize(file_content, annotation_block)
+        @file_content = file_content
+        @annotation_block = annotation_block
+      end
+
+      def generate
+        # Ignore the Schema version line because it changes with each migration
+        current_annotations = @file_content.match(HEADER_PATTERN).to_s
+        new_annotations = @annotation_block.match(HEADER_PATTERN).to_s
+
+        if current_annotations.present?
+          current_annotation_columns = current_annotations.scan(COLUMN_PATTERN).sort
+        else
+          current_annotation_columns = []
+        end
+
+        if new_annotations.present?
+          new_annotation_columns = new_annotations.scan(COLUMN_PATTERN).sort
+        else
+          new_annotation_columns = []
+        end
+
+        _result = AnnotationDiff.new(current_annotation_columns, new_annotation_columns)
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/annotation_generator.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class AnnotationGenerator
+      # Annotate Models plugin use this header
+      PREFIX = '== Schema Information'.freeze
+      PREFIX_MD = '## Schema Information'.freeze
+
+      END_MARK = '== Schema Information End'.freeze
+
+      MD_NAMES_OVERHEAD = 6
+      MD_TYPE_ALLOWANCE = 18
+
+      def initialize(klass, options = {})
+        @model = ModelWrapper.new(klass, options)
+        @options = options
+        @info = "" # TODO: Make array and build string that way
+      end
+
+      def generate
+        @info = "# #{header}\n"
+        @info += schema_header_text
+
+        max_size = @model.max_schema_info_width
+
+        if @options[:format_markdown]
+          @info += format("# %-#{max_size + MD_NAMES_OVERHEAD}.#{max_size + MD_NAMES_OVERHEAD}s | %-#{MD_TYPE_ALLOWANCE}.#{MD_TYPE_ALLOWANCE}s | %s\n",
+                          'Name',
+                          'Type',
+                          'Attributes')
+          @info += "# #{'-' * (max_size + MD_NAMES_OVERHEAD)} | #{'-' * MD_TYPE_ALLOWANCE} | #{'-' * 27}\n"
+        end
+
+        @info += @model.columns.map do |col|
+          ColumnAnnotationBuilder.new(col, @model, max_size, @options).build
+        end.join
+
+        if @options[:show_indexes] && @model.table_exists?
+          @info += IndexAnnotationBuilder.new(@model, @options).build
+        end
+
+        if @options[:show_foreign_keys] && @model.table_exists?
+          @info += ForeignKeyAnnotationBuilder.new(@model, @options).build
+        end
+
+        @info += schema_footer_text
+
+        @info
+      end
+
+      def header
+        header = @options[:format_markdown] ? PREFIX_MD.dup : PREFIX.dup
+        version = ActiveRecord::Migrator.current_version rescue 0
+
+        if @options[:include_version] && version > 0
+          header += "\n# Schema version: #{version}"
+        end
+
+        header
+      end
+
+      def schema_header_text
+        info = []
+        info << "#"
+
+        if @options[:format_markdown]
+          info << "# Table name: `#{@model.table_name}`"
+          info << "#"
+          info << "# ### Columns"
+        else
+          info << "# Table name: #{@model.table_name}"
+        end
+        info << "#\n" # We want the last line break
+
+        info.join("\n")
+      end
+
+      def schema_footer_text
+        info = []
+
+        if @options[:format_rdoc]
+          info << "#--"
+          info << "# #{END_MARK}"
+          info << "#++\n"
+        else
+          info << "#\n"
+        end
+
+        info.join("\n")
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/annotator.rb

@@ -1,31 +1,20 @@
-# require 'bigdecimal'
+# frozen_string_literal: true
 
 module AnnotateRb
   module ModelAnnotator
     class Annotator
-      # Annotate Models plugin use this header
-      PREFIX = '== Schema Information'.freeze
-      PREFIX_MD = '## Schema Information'.freeze
-
-      MAGIC_COMMENT_MATCHER = Regexp.new(/(^#\s*encoding:.*(?:\n|r\n))|(^# coding:.*(?:\n|\r\n))|(^# -\*- coding:.*(?:\n|\r\n))|(^# -\*- encoding\s?:.*(?:\n|\r\n))|(^#\s*frozen_string_literal:.+(?:\n|\r\n))|(^# -\*- frozen_string_literal\s*:.+-\*-(?:\n|\r\n))/).freeze
-
       class << self
-        # We're passed a name of things that might be
-        # ActiveRecord models. If we can find the class, and
-        # if its a subclass of ActiveRecord::Base,
-        # then pass it to the associated block
         def do_annotations(options = {})
-          header = options[:format_markdown] ? PREFIX_MD.dup : PREFIX.dup
-          version = ActiveRecord::Migrator.current_version rescue 0
-          if options[:include_version] && version > 0
-            header << "\n# Schema version: #{version}"
-          end
-
           annotated = []
-          model_files_to_annotate = ModelFilesGetter.call(options)
 
-          model_files_to_annotate.each do |path, filename|
-            ModelFileAnnotator.call(annotated, File.join(path, filename), header, options)
+          model_files_to_consider = ModelFilesGetter.call(options)
+
+          model_files_to_consider.each do |path, filename|
+            file = File.join(path, filename)
+
+            if AnnotationDecider.new(file, options).annotate?
+              ModelFileAnnotator.call(annotated, file, options)
+            end
           end
 
           if annotated.empty?
@@ -37,34 +26,41 @@ module AnnotateRb
 
         def remove_annotations(options = {})
           deannotated = []
-          deannotated_klass = false
-          ModelFilesGetter.call(options).each do |file|
-            file = File.join(file)
+
+          model_files_to_consider = ModelFilesGetter.call(options)
+
+          model_files_to_consider.each do |path, filename|
+            deannotated_klass = false
+            file = File.join(path, filename)
+
             begin
               klass = ModelClassGetter.call(file, options)
               if klass < ActiveRecord::Base && !klass.abstract_class?
                 model_name = klass.name.underscore
                 table_name = klass.table_name
-                model_file_name = file
-                deannotated_klass = true if FileAnnotationRemover.call(model_file_name, options)
 
-                patterns = PatternGetter.call(options)
+                if FileAnnotationRemover.call(file, options)
+                  deannotated_klass = true
+                end
+
+                related_files = RelatedFilesListBuilder.new(file, model_name, table_name, options).build
 
-                patterns
-                  .map { |f| FileNameResolver.call(f, model_name, table_name) }
-                  .each do |f|
+                related_files.each do |f, _position_key|
                   if File.exist?(f)
                     FileAnnotationRemover.call(f, options)
-                    deannotated_klass = true
                   end
                 end
               end
-              deannotated << klass if deannotated_klass
+
+              if deannotated_klass
+                deannotated << klass
+              end
             rescue StandardError => e
               $stderr.puts "Unable to deannotate #{File.join(file)}: #{e.message}"
               $stderr.puts "\t" + e.backtrace.join("\n\t") if options[:trace]
             end
           end
+
           puts "Removed annotations from: #{deannotated.join(', ')}"
         end
       end

data/lib/annotate_rb/model_annotator/column_annotation_builder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class ColumnAnnotationBuilder
+      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 = ColumnAttributesBuilder.new(@column, @options, is_primary_key, column_indices).build
+        formatted_column_type = ColumnTypeBuilder.new(@column, @options).build
+
+        col_name = if @model.with_comments? && @column.comment
+                     "#{@column.name}(#{@column.comment.gsub(/\n/, '\\n')})"
+                   else
+                     @column.name
+                   end
+
+        if @options[:format_rdoc]
+          result += format("# %-#{@max_size}.#{@max_size}s<tt>%s</tt>",
+                           "*#{col_name}*::",
+                           column_attributes.unshift(formatted_column_type).join(', ')).rstrip + "\n"
+        elsif @options[:format_yard]
+          result += sprintf("# @!attribute #{col_name}") + "\n"
+
+          if @column.respond_to?(:array) && @column.array
+            ruby_class = "Array<#{Helper.map_col_type_to_ruby_classes(formatted_column_type)}>"
+          else
+            ruby_class = Helper.map_col_type_to_ruby_classes(formatted_column_type)
+          end
+
+          result += sprintf("#   @return [#{ruby_class}]") + "\n"
+        elsif @options[:format_markdown]
+          name_remainder = @max_size - col_name.length - Helper.non_ascii_length(col_name)
+          type_remainder = (MD_TYPE_ALLOWANCE - 2) - formatted_column_type.length
+          result += format("# **`%s`**%#{name_remainder}s | `%s`%#{type_remainder}s | `%s`",
+                           col_name,
+                           ' ',
+                           formatted_column_type,
+                           ' ',
+                           column_attributes.join(', ').rstrip).gsub('``', '  ').rstrip + "\n"
+        else
+          result += format_default(col_name, @max_size, formatted_column_type, column_attributes)
+        end
+
+        result
+      end
+
+      private
+
+      def format_default(col_name, max_size, col_type, attrs)
+        format('#  %s:%s %s',
+               Helper.mb_chars_ljust(col_name, max_size),
+               Helper.mb_chars_ljust(col_type, BARE_TYPE_ALLOWANCE),
+               attrs.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
+          else
+            # If model has 1 primary key, check if this column is it
+            if column_name.to_sym == model.primary_key.to_sym
+              return true
+            end
+          end
+        end
+
+        false
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/column_attributes_builder.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class ColumnAttributesBuilder
+      # 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 }
+
+            if indexed_columns.empty?
+              attrs << 'indexed'
+            else
+              attrs << "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

data/lib/annotate_rb/model_annotator/column_type_builder.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class ColumnTypeBuilder
+      # 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.
+        else
+          if @column.limit && !@options[:format_yard]
+            if !@column.limit.is_a?(Array) && !hide_limit?
+              formatted_column_type = column_type + "(#{@column.limit})"
+            end
+          end
+        end
+
+        formatted_column_type
+      end
+
+      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

data/lib/annotate_rb/model_annotator/column_wrapper.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    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
+        Helper.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
+    end
+  end
+end