annotaterb 4.0.0 → 4.1.0

data/lib/annotate_rb/model_annotator/foreign_key_annotation_builder.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class ForeignKeyAnnotationBuilder
+      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

data/lib/annotate_rb/model_annotator/helper.rb

@@ -3,51 +3,104 @@
 module AnnotateRb
   module ModelAnnotator
     module Helper
-      MATCHED_TYPES = %w(test fixture factory serializer scaffold controller helper).freeze
+      INDEX_CLAUSES = {
+        unique: {
+          default: 'UNIQUE',
+          markdown: '_unique_'
+        },
+        where: {
+          default: 'WHERE',
+          markdown: '_where_'
+        },
+        using: {
+          default: 'USING',
+          markdown: '_using_'
+        }
+      }.freeze
 
       class << self
-        def matched_types(options)
-          types = MATCHED_TYPES.dup
-          types << 'admin' if options[:active_admin] =~ Constants::TRUE_RE && !types.include?('admin')
-          types << 'additional_file_patterns' if options[:additional_file_patterns].present?
+        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
 
-          types
+        def index_unique_info(index, format = :default)
+          index.unique ? " #{INDEX_CLAUSES[:unique][format]}" : ''
         end
 
-        def magic_comments_as_string(content)
-          magic_comments = content.scan(Annotator::MAGIC_COMMENT_MATCHER).flatten.compact
+        def index_where_info(index, format = :default)
+          value = index.try(:where).try(:to_s)
+          if value.blank?
+            ''
+          else
+            " #{INDEX_CLAUSES[:where][format]} #{value}"
+          end
+        end
 
-          if magic_comments.any?
-            magic_comments.join
+        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
 
-        def skip_on_migration?
-          Env.read('ANNOTATE_SKIP_ON_DB_MIGRATE') =~ Constants::TRUE_RE || Env.read('skip_on_db_migrate') =~ Constants::TRUE_RE
+        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 non_ascii_length(string)
+          string.to_s.chars.reject(&:ascii_only?).length
         end
 
-        def include_routes?
-          Env.read('routes') =~ Constants::TRUE_RE
+        # 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
 
-        def include_models?
-          Env.read('models') =~ Constants::TRUE_RE
+        def width(string)
+          string.chars.inject(0) { |acc, elem| acc + (elem.bytesize == 3 ? 2 : 1) }
         end
 
-        def true?(val)
-          val.present? && Constants::TRUE_RE.match?(val)
+        def magic_comments_as_string(content)
+          magic_comments = content.scan(Constants::MAGIC_COMMENT_MATCHER).flatten.compact
+
+          if magic_comments.any?
+            magic_comments.join
+          else
+            ''
+          end
         end
 
         # TODO: Find another implementation that doesn't depend on ActiveSupport
         def fallback(*args)
           args.compact.detect(&:present?)
         end
-
-        def reset_options(options)
-          options.flatten.each { |key| Env.write(key, nil) }
-        end
       end
     end
   end

data/lib/annotate_rb/model_annotator/index_annotation_builder.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class IndexAnnotationBuilder
+      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
+
+        indexes = @model.retrieve_indexes_from_table
+        return '' 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 final_index_string_in_markdown(index)
+        details = format(
+          '%s%s%s',
+          Helper.index_unique_info(index, :markdown),
+          Helper.index_where_info(index, :markdown),
+          Helper.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(',')})",
+          Helper.index_unique_info(index),
+          Helper.index_where_info(index),
+          Helper.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
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/model_file_annotator.rb

@@ -2,36 +2,21 @@
 
 module AnnotateRb
   module ModelAnnotator
-    # Not sure yet what the difference is between this and FileAnnotator
+    # Annotates a model file and its related files (controllers, factories, etc)
     class ModelFileAnnotator
       class << self
-        def call(annotated, file, header, options)
+        def call(annotated, file, options)
           begin
-            return false if /#{Constants::SKIP_ANNOTATION_PREFIX}.*/ =~ (File.exist?(file) ? File.read(file) : '')
             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.abstract_class?
-            klass_table_exists = 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
-            ]
-
-            do_annotate = annotate_conditions.all?
-
-            if do_annotate
-              files_annotated = annotate(klass, file, header, options)
-              annotated.concat(files_annotated)
+            instructions = build_instructions(klass, file, options)
+            instructions.each do |instruction|
+              if FileAnnotator.call_with_instructions(instruction)
+                annotated << instruction.file
+              end
             end
 
+            annotated
           rescue BadModelFileError => e
             unless options[:ignore_unknown_models]
               $stderr.puts "Unable to annotate #{file}: #{e.message}"
@@ -45,72 +30,24 @@ module AnnotateRb
 
         private
 
-        # Given the name of an ActiveRecord class, create a schema
-        # info block (basically a comment containing information
-        # on the columns and their types) and put it at the front
-        # of the model and fixture source files.
-        #
-        # === Options (opts)
-        #  :position_in_class<Symbol>:: where to place the annotated section in model file
-        #  :position_in_test<Symbol>:: where to place the annotated section in test/spec file(s)
-        #  :position_in_fixture<Symbol>:: where to place the annotated section in fixture file
-        #  :position_in_factory<Symbol>:: where to place the annotated section in factory file
-        #  :position_in_serializer<Symbol>:: where to place the annotated section in serializer file
-        #  :exclude_tests<Symbol>:: whether to skip modification of test/spec files
-        #  :exclude_fixtures<Symbol>:: whether to skip modification of fixture files
-        #  :exclude_factories<Symbol>:: whether to skip modification of factory files
-        #  :exclude_serializers<Symbol>:: whether to skip modification of serializer files
-        #  :exclude_scaffolds<Symbol>:: whether to skip modification of scaffold files
-        #  :exclude_controllers<Symbol>:: whether to skip modification of controller files
-        #  :exclude_helpers<Symbol>:: whether to skip modification of helper files
-        #  :exclude_sti_subclasses<Symbol>:: whether to skip modification of files for STI subclasses
-        #
-        # == Returns:
-        # an array of file names that were annotated.
-        #
-        def annotate(klass, file, header, options = {})
-          begin
-            klass.reset_column_information
-            info = SchemaInfo.generate(klass, header, options)
-            model_name = klass.name.underscore
-            table_name = klass.table_name
-            model_file_name = File.join(file)
-            annotated = []
-
-            if FileAnnotator.call(model_file_name, info, :position_in_class, options)
-              annotated << model_file_name
-            end
-
-            Helper.matched_types(options).each do |key|
-              exclusion_key = "exclude_#{key.pluralize}".to_sym
-              position_key = "position_in_#{key}".to_sym
-
-              # Same options for active_admin models
-              if key == 'admin'
-                exclusion_key = 'exclude_class'.to_sym
-                position_key = 'position_in_class'.to_sym
-              end
+        def build_instructions(klass, file, options = {})
+          instructions = []
 
-              next if options[exclusion_key]
+          klass.reset_column_information
+          annotation = AnnotationGenerator.new(klass, options).generate
+          model_name = klass.name.underscore
+          table_name = klass.table_name
 
-              patterns = PatternGetter.call(options, key)
+          model_instruction = FileAnnotatorInstruction.new(file, annotation, :position_in_class, options)
+          instructions << model_instruction
 
-              patterns
-                .map { |f| FileNameResolver.call(f, model_name, table_name) }
-                .map { |f| Dir.glob(f) }
-                .flatten
-                .each do |f|
-                if FileAnnotator.call(f, info, position_key, options)
-                  annotated << f
-                end
-              end
-            end
-          rescue StandardError => e
-            $stderr.puts "Unable to annotate #{file}: #{e.message}"
-            $stderr.puts "\t" + e.backtrace.join("\n\t") if options[:trace]
+          related_files = RelatedFilesListBuilder.new(file, model_name, table_name, options).build
+          related_file_instructions = related_files.map do |f, position_key|
+            _instruction = FileAnnotatorInstruction.new(f, annotation, position_key, options)
           end
+          instructions.concat(related_file_instructions)
 
-          annotated
+          instructions
         end
       end
     end

data/lib/annotate_rb/model_annotator/model_files_getter.rb

@@ -11,6 +11,8 @@ module AnnotateRb
         def call(options)
           model_files = []
 
+          # Note: This is currently broken as we don't set `is_rake` anywhere.
+          # It's an artifact from the old Annotate gem and how it did control flow.
           model_files = list_model_files_from_argument(options) if !options[:is_rake]
 
           return model_files if !model_files.empty?
@@ -30,7 +32,7 @@ module AnnotateRb
         rescue SystemCallError
           $stderr.puts "No models found in directory '#{options[:model_dir].join("', '")}'."
           $stderr.puts "Either specify models on the command line, or use the --model-dir option."
-          $stderr.puts "Call 'annotate --help' for more info."
+          $stderr.puts "Call 'annotaterb --help' for more info."
           # exit 1 # TODO: Return exit code back to caller. Right now it messes up RSpec being able to run
         end
 
@@ -50,7 +52,7 @@ module AnnotateRb
 
           if model_files.size != specified_files.size
             $stderr.puts "The specified file could not be found in directory '#{options[:model_dir].join("', '")}'."
-            $stderr.puts "Call 'annotate --help' for more info."
+            $stderr.puts "Call 'annotaterb --help' for more info."
             # exit 1 # TODO: Return exit code back to caller. Right now it messes up RSpec being able to run
           end
 

data/lib/annotate_rb/model_annotator/model_wrapper.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class ModelWrapper
+      # Should be the wrapper for an ActiveRecord model that serves as the source of truth of the model
+      # of the model that we're annotating
+
+      def initialize(klass, options = {})
+        @klass = klass
+        @options = options
+      end
+
+      # Gets the columns of the ActiveRecord model, processes them, and then returns them.
+      def columns
+        @columns ||= begin
+                       cols = raw_columns
+                       cols += translated_columns
+
+                       ignore_columns = @options[:ignore_columns]
+                       if ignore_columns
+                         cols = cols.reject do |col|
+                           col.name.match(/#{ignore_columns}/)
+                         end
+                       end
+
+                       cols = cols.sort_by(&:name) if @options[:sort]
+                       cols = classified_sort(cols) if @options[:classified_sort]
+
+                       cols
+                     end
+      end
+
+      def connection
+        @klass.connection
+      end
+
+      # Returns the unmodified model columns
+      def raw_columns
+        @raw_columns ||= @klass.columns
+      end
+
+      def primary_key
+        @klass.primary_key
+      end
+
+      def table_exists?
+        @klass.table_exists?
+      end
+
+      def column_defaults
+        @klass.column_defaults
+      end
+
+      # Add columns managed by the globalize gem if this gem is being used.
+      # TODO: Audit if this is still needed, it seems like Globalize gem is no longer maintained
+      def translated_columns
+        return [] unless @klass.respond_to?(:translation_class)
+
+        ignored_cols = ignored_translation_table_columns
+
+        @klass.translation_class.columns.reject do |col|
+          ignored_cols.include? col.name.to_sym
+        end
+      end
+
+      def table_name
+        @klass.table_name
+      end
+
+      def model_name
+        @klass.name.underscore
+      end
+
+      # Calculates the max width of the schema for the model by looking at the columns, schema comments, with respect
+      # to the options.
+      def max_schema_info_width
+        cols = columns
+
+        if with_comments?
+          max_size = cols.map do |column|
+            column.name.size + (column.comment ? Helper.width(column.comment) : 0)
+          end.max || 0
+          max_size += 2
+        else
+          max_size = cols.map(&:name).map(&:size).max
+        end
+        max_size += @options[:format_rdoc] ? 5 : 1
+
+        max_size
+      end
+
+      def retrieve_indexes_from_table
+        table_name = @klass.table_name
+        return [] unless table_name
+
+        indexes = @klass.connection.indexes(table_name)
+        return indexes if indexes.any? || !@klass.table_name_prefix
+
+        # Try to search the table without prefix
+        table_name_without_prefix = table_name.to_s.sub(@klass.table_name_prefix, '')
+        @klass.connection.indexes(table_name_without_prefix)
+      end
+
+      def with_comments?
+        @options[:with_comment] &&
+          raw_columns.first.respond_to?(:comment) &&
+          raw_columns.map(&:comment).any? { |comment| !comment.nil? }
+      end
+
+      def classified_sort(cols)
+        rest_cols = []
+        timestamps = []
+        associations = []
+        id = nil
+
+        cols.each do |c|
+          if c.name.eql?('id')
+            id = c
+          elsif c.name.eql?('created_at') || c.name.eql?('updated_at')
+            timestamps << c
+          elsif c.name[-3, 3].eql?('_id')
+            associations << c
+          else
+            rest_cols << c
+          end
+        end
+        [rest_cols, timestamps, associations].each { |a| a.sort_by!(&:name) }
+
+        ([id] << rest_cols << timestamps << associations).flatten.compact
+      end
+
+      # These are the columns that the globalize gem needs to work but
+      # are not necessary for the models to be displayed as annotations.
+      def ignored_translation_table_columns
+        # Construct the foreign column name in the translations table
+        # eg. Model: Car, foreign column name: car_id
+        foreign_column_name = [
+          @klass.translation_class.to_s
+               .gsub('::Translation', '').gsub('::', '_')
+               .downcase,
+          '_id'
+        ].join.to_sym
+
+        [
+          :id,
+          :created_at,
+          :updated_at,
+          :locale,
+          foreign_column_name
+        ]
+      end
+    end
+  end
+end