annotate 3.0.3 → 3.1.1

data/RELEASE.md

@@ -0,0 +1,19 @@
+## Prerequisite 
+
+- Install "git-flow" (`brew install git-flow`)
+- Install "bump" gem (`gem install bump`)
+
+
+## Perform a release
+
+- `git flow release start <release>`
+- Update the `CHANGELOG.md` file
+- `bump current`
+- `bump patch`
+- `rm -rf dist`
+- `rake spec`
+- `rake gem`
+- `git flow release finish <release>`
+
+- `rake gem:publish`
+

data/annotate.gemspec

@@ -7,14 +7,14 @@ Gem::Specification.new do |s|
   s.name = 'annotate'
   s.version = Annotate.version
 
-  s.required_ruby_version = '>= 2.2.0'
+  s.required_ruby_version = '>= 2.4.0'
   s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to? :required_rubygems_version=
   s.authors = ['Alex Chaffee', 'Cuong Tran', 'Marcos Piccinini', 'Turadg Aleahmad', 'Jon Frisby']
   s.description = 'Annotates Rails/ActiveRecord Models, routes, fixtures, and others based on the database schema.'
   s.email = ['alex@stinky.com', 'cuong.tran@gmail.com', 'x@nofxx.com', 'turadg@aleahmad.net', 'jon@cloudability.com']
   s.executables = ['annotate']
-  s.extra_rdoc_files = ['README.rdoc', 'CHANGELOG.rdoc', 'TODO.rdoc']
-  s.files = `git ls-files -z LICENSE.txt *.rdoc *.gemspec bin lib`.split("\x0")
+  s.extra_rdoc_files = ['README.md', 'CHANGELOG.md']
+  s.files = `git ls-files -z LICENSE.txt *.md *.gemspec bin lib`.split("\x0")
   s.homepage = 'http://github.com/ctran/annotate_models'
   s.licenses = ['Ruby']
   s.require_paths = ['lib']

data/bin/annotate

@@ -26,7 +26,7 @@ exit if options_result[:exit]
 options = Annotate.setup_options(
   is_rake: ENV['is_rake'] && !ENV['is_rake'].empty?
 )
-Annotate.eager_load(options) if Annotate.include_models?
+Annotate.eager_load(options) if Annotate::Helpers.include_models?
 
-AnnotateModels.send(options_result[:target_action], options) if Annotate.include_models?
-AnnotateRoutes.send(options_result[:target_action], options) if Annotate.include_routes?
+AnnotateModels.send(options_result[:target_action], options) if Annotate::Helpers.include_models?
+AnnotateRoutes.send(options_result[:target_action], options) if Annotate::Helpers.include_routes?

data/lib/annotate.rb

@@ -1,10 +1,9 @@
-# rubocop:disable  Metrics/ModuleLength
-
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 require 'annotate/version'
 require 'annotate/annotate_models'
 require 'annotate/annotate_routes'
 require 'annotate/constants'
+require 'annotate/helpers'
 
 begin
   # ActiveSupport 3.x...
@@ -17,36 +16,6 @@ rescue StandardError
 end
 
 module Annotate
-  ##
-  # The set of available options to customize the behavior of Annotate.
-  #
-  POSITION_OPTIONS = [
-    :position_in_routes, :position_in_class, :position_in_test,
-    :position_in_fixture, :position_in_factory, :position,
-    :position_in_serializer
-  ].freeze
-  FLAG_OPTIONS = [
-    :show_indexes, :simple_indexes, :include_version, :exclude_tests,
-    :exclude_fixtures, :exclude_factories, :ignore_model_sub_dir,
-    :format_bare, :format_rdoc, :format_markdown, :sort, :force, :frozen,
-    :trace, :timestamp, :exclude_serializers, :classified_sort,
-    :show_foreign_keys, :show_complete_foreign_keys,
-    :exclude_scaffolds, :exclude_controllers, :exclude_helpers,
-    :exclude_sti_subclasses, :ignore_unknown_models, :with_comment
-  ].freeze
-  OTHER_OPTIONS = [
-    :additional_file_patterns, :ignore_columns, :skip_on_db_migrate, :wrapper_open, :wrapper_close,
-    :wrapper, :routes, :models, :hide_limit_column_types, :hide_default_column_types,
-    :ignore_routes, :active_admin
-  ].freeze
-  PATH_OPTIONS = [
-    :require, :model_dir, :root_dir
-  ].freeze
-
-  def self.all_options
-    [POSITION_OPTIONS, FLAG_OPTIONS, PATH_OPTIONS, OTHER_OPTIONS]
-  end
-
   ##
   # Set default values that can be overridden via environment variables.
   #
@@ -54,9 +23,9 @@ module Annotate
     return if @has_set_defaults
     @has_set_defaults = true
 
-    options = HashWithIndifferentAccess.new(options)
+    options = ActiveSupport::HashWithIndifferentAccess.new(options)
 
-    all_options.flatten.each do |key|
+    Constants::ALL_ANNOTATE_OPTIONS.flatten.each do |key|
       if options.key?(key)
         default_value = if options[key].is_a?(Array)
                           options[key].join(',')
@@ -74,69 +43,42 @@ module Annotate
   # TODO: what is the difference between this and set_defaults?
   #
   def self.setup_options(options = {})
-    POSITION_OPTIONS.each do |key|
-      options[key] = fallback(ENV[key.to_s], ENV['position'], 'before')
+    Constants::POSITION_OPTIONS.each do |key|
+      options[key] = Annotate::Helpers.fallback(ENV[key.to_s], ENV['position'], 'before')
     end
-    FLAG_OPTIONS.each do |key|
-      options[key] = true?(ENV[key.to_s])
+    Constants::FLAG_OPTIONS.each do |key|
+      options[key] = Annotate::Helpers.true?(ENV[key.to_s])
     end
-    OTHER_OPTIONS.each do |key|
+    Constants::OTHER_OPTIONS.each do |key|
       options[key] = !ENV[key.to_s].blank? ? ENV[key.to_s] : nil
     end
-    PATH_OPTIONS.each do |key|
+    Constants::PATH_OPTIONS.each do |key|
       options[key] = !ENV[key.to_s].blank? ? ENV[key.to_s].split(',') : []
     end
 
     options[:additional_file_patterns] ||= []
+    options[:additional_file_patterns] = options[:additional_file_patterns].split(',') if options[:additional_file_patterns].is_a?(String)
     options[:model_dir] = ['app/models'] if options[:model_dir].empty?
 
     options[:wrapper_open] ||= options[:wrapper]
     options[:wrapper_close] ||= options[:wrapper]
 
     # These were added in 2.7.0 but so this is to revert to old behavior by default
-    options[:exclude_scaffolds] = Annotate.true?(ENV.fetch('exclude_scaffolds', 'true'))
-    options[:exclude_controllers] = Annotate.true?(ENV.fetch('exclude_controllers', 'true'))
-    options[:exclude_helpers] = Annotate.true?(ENV.fetch('exclude_helpers', 'true'))
+    options[:exclude_scaffolds] = Annotate::Helpers.true?(ENV.fetch('exclude_scaffolds', 'true'))
+    options[:exclude_controllers] = Annotate::Helpers.true?(ENV.fetch('exclude_controllers', 'true'))
+    options[:exclude_helpers] = Annotate::Helpers.true?(ENV.fetch('exclude_helpers', 'true'))
 
     options
   end
 
-  def self.reset_options
-    all_options.flatten.each { |key| ENV[key.to_s] = nil }
-  end
-
-  def self.skip_on_migration?
-    ENV['ANNOTATE_SKIP_ON_DB_MIGRATE'] =~ Constants::TRUE_RE || ENV['skip_on_db_migrate'] =~ Constants::TRUE_RE
-  end
-
-  def self.include_routes?
-    ENV['routes'] =~ Constants::TRUE_RE
-  end
-
-  def self.include_models?
-    ENV['models'] =~ Constants::TRUE_RE
-  end
-
-  def self.loaded_tasks=(val)
-    @loaded_tasks = val
-  end
-
-  def self.loaded_tasks
-    @loaded_tasks
-  end
-
   def self.load_tasks
-    return if loaded_tasks
-    self.loaded_tasks = true
+    return if @tasks_loaded
 
     Dir[File.join(File.dirname(__FILE__), 'tasks', '**/*.rake')].each do |rake|
       load rake
     end
-  end
 
-  def self.load_requires(options)
-    options[:require].count > 0 &&
-      options[:require].each { |path| require path }
+    @tasks_loaded = true
   end
 
   def self.eager_load(options)
@@ -192,13 +134,12 @@ module Annotate
     Rake::Task[:set_annotation_options].invoke
   end
 
-  def self.fallback(*args)
-    args.detect { |arg| !arg.blank? }
-  end
+  class << self
+    private
 
-  def self.true?(val)
-    return false if val.blank?
-    return false unless val =~ Constants::TRUE_RE
-    true
+    def load_requires(options)
+      options[:require].count > 0 &&
+        options[:require].each { |path| require path }
+    end
   end
 end

data/lib/annotate/annotate_models.rb

@@ -38,9 +38,9 @@ module AnnotateModels
   BLUEPRINTS_TEST_DIR   = File.join('test', "blueprints")
   BLUEPRINTS_SPEC_DIR   = File.join('spec', "blueprints")
 
-  # Factory Girl http://github.com/thoughtbot/factory_girl
-  FACTORY_GIRL_TEST_DIR = File.join('test', "factories")
-  FACTORY_GIRL_SPEC_DIR = File.join('spec', "factories")
+  # Factory Bot https://github.com/thoughtbot/factory_bot
+  FACTORY_BOT_TEST_DIR = File.join('test', "factories")
+  FACTORY_BOT_SPEC_DIR = File.join('spec', "factories")
 
   # Fabrication https://github.com/paulelliott/fabrication.git
   FABRICATORS_TEST_DIR  = File.join('test', "fabricators")
@@ -82,6 +82,8 @@ module AnnotateModels
     }
   }.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
     def annotate_pattern(options = {})
       if options[:wrapper_open]
@@ -140,12 +142,12 @@ module AnnotateModels
         File.join(root_directory, EXEMPLARS_SPEC_DIR,     "%MODEL_NAME%_exemplar.rb"),
         File.join(root_directory, BLUEPRINTS_TEST_DIR,    "%MODEL_NAME%_blueprint.rb"),
         File.join(root_directory, BLUEPRINTS_SPEC_DIR,    "%MODEL_NAME%_blueprint.rb"),
-        File.join(root_directory, FACTORY_GIRL_TEST_DIR,  "%MODEL_NAME%_factory.rb"),    # (old style)
-        File.join(root_directory, FACTORY_GIRL_SPEC_DIR,  "%MODEL_NAME%_factory.rb"),    # (old style)
-        File.join(root_directory, FACTORY_GIRL_TEST_DIR,  "%TABLE_NAME%.rb"),            # (new style)
-        File.join(root_directory, FACTORY_GIRL_SPEC_DIR,  "%TABLE_NAME%.rb"),            # (new style)
-        File.join(root_directory, FACTORY_GIRL_TEST_DIR,  "%PLURALIZED_MODEL_NAME%.rb"), # (new style)
-        File.join(root_directory, FACTORY_GIRL_SPEC_DIR,  "%PLURALIZED_MODEL_NAME%.rb"), # (new style)
+        File.join(root_directory, FACTORY_BOT_TEST_DIR,  "%MODEL_NAME%_factory.rb"),    # (old style)
+        File.join(root_directory, FACTORY_BOT_SPEC_DIR,  "%MODEL_NAME%_factory.rb"),    # (old style)
+        File.join(root_directory, FACTORY_BOT_TEST_DIR,  "%TABLE_NAME%.rb"),            # (new style)
+        File.join(root_directory, FACTORY_BOT_SPEC_DIR,  "%TABLE_NAME%.rb"),            # (new style)
+        File.join(root_directory, FACTORY_BOT_TEST_DIR,  "%PLURALIZED_MODEL_NAME%.rb"), # (new style)
+        File.join(root_directory, FACTORY_BOT_SPEC_DIR,  "%PLURALIZED_MODEL_NAME%.rb"), # (new style)
         File.join(root_directory, FABRICATORS_TEST_DIR,   "%MODEL_NAME%_fabricator.rb"),
         File.join(root_directory, FABRICATORS_SPEC_DIR,   "%MODEL_NAME%_fabricator.rb")
       ]
@@ -154,7 +156,7 @@ module AnnotateModels
     def serialize_files(root_directory)
       [
         File.join(root_directory, SERIALIZERS_DIR,       "%MODEL_NAME%_serializer.rb"),
-        File.join(root_directory, SERIALIZERS_TEST_DIR,  "%MODEL_NAME%_serializer_spec.rb"),
+        File.join(root_directory, SERIALIZERS_TEST_DIR,  "%MODEL_NAME%_serializer_test.rb"),
         File.join(root_directory, SERIALIZERS_SPEC_DIR,  "%MODEL_NAME%_serializer_spec.rb")
       ]
     end
@@ -244,16 +246,7 @@ module AnnotateModels
         info << "# #{ '-' * ( max_size + md_names_overhead ) } | #{'-' * md_type_allowance} | #{ '-' * 27 }\n"
       end
 
-      cols = if ignore_columns = options[:ignore_columns]
-               klass.columns.reject do |col|
-                 col.name.match(/#{ignore_columns}/)
-               end
-             else
-               klass.columns
-             end
-
-      cols = cols.sort_by(&:name) if options[:sort]
-      cols = classified_sort(cols) if options[:classified_sort]
+      cols = columns(klass, options)
       cols.each do |col|
         col_type = get_col_type(col)
         attrs = []
@@ -264,8 +257,8 @@ module AnnotateModels
 
         if col_type == 'decimal'
           col_type << "(#{col.precision}, #{col.scale})"
-        elsif col_type != 'spatial'
-          if col.limit
+        elsif !%w[spatial geometry geography].include?(col_type)
+          if col.limit && !options[:format_yard]
             if col.limit.is_a? Array
               attrs << "(#{col.limit.join(', ')})"
             else
@@ -304,8 +297,12 @@ module AnnotateModels
                    end
         if options[:format_rdoc]
           info << sprintf("# %-#{max_size}.#{max_size}s<tt>%s</tt>", "*#{col_name}*::", attrs.unshift(col_type).join(", ")).rstrip + "\n"
+        elsif options[:format_yard]
+          info << sprintf("# @!attribute #{col_name}") + "\n"
+          ruby_class = col.respond_to?(:array) && col.array ? "Array<#{map_col_type_to_ruby_classes(col_type)}>": map_col_type_to_ruby_classes(col_type)
+          info << sprintf("#   @return [#{ruby_class}]") + "\n"
         elsif options[:format_markdown]
-          name_remainder = max_size - col_name.length
+          name_remainder = max_size - col_name.length - non_ascii_length(col_name)
           type_remainder = (md_type_allowance - 2) - col_type.length
           info << (sprintf("# **`%s`**%#{name_remainder}s | `%s`%#{type_remainder}s | `%s`", col_name, " ", col_type, " ", attrs.join(", ").rstrip)).gsub('``', '  ').rstrip + "\n"
         else
@@ -472,7 +469,10 @@ module AnnotateModels
       foreign_keys = klass.connection.foreign_keys(klass.table_name)
       return '' if foreign_keys.empty?
 
-      format_name = ->(fk) { options[:show_complete_foreign_keys] ? fk.name : fk.name.gsub(/(?<=^fk_rails_)[0-9a-f]{10}$/, '...') }
+      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|
@@ -515,7 +515,7 @@ module AnnotateModels
       old_header = old_content.match(header_pattern).to_s
       new_header = info_block.match(header_pattern).to_s
 
-      column_pattern = /^#[\t ]+[\w\*`]+[\t ]+.+$/
+      column_pattern = /^#[\t ]+[\w\*\.`]+[\t ]+.+$/
       old_columns = old_header && old_header.scan(column_pattern).sort
       new_columns = new_header && new_header.scan(column_pattern).sort
 
@@ -534,15 +534,15 @@ module AnnotateModels
       # need to insert it in correct position
       if old_annotation.empty? || options[:force]
         magic_comments_block = magic_comments_as_string(old_content)
-        old_content.gsub!(magic_comment_matcher, '')
+        old_content.gsub!(MAGIC_COMMENT_MATCHER, '')
         old_content.sub!(annotate_pattern(options), '')
 
         new_content = if %w(after bottom).include?(options[position].to_s)
                         magic_comments_block + (old_content.rstrip + "\n\n" + wrapped_info_block)
                       elsif magic_comments_block.empty?
-                        magic_comments_block + wrapped_info_block + "\n" + old_content
+                        magic_comments_block + wrapped_info_block + old_content.lstrip
                       else
-                        magic_comments_block + "\n" + wrapped_info_block + "\n" + old_content
+                        magic_comments_block + "\n" + wrapped_info_block + old_content.lstrip
                       end
       else
         # replace the old annotation with the new one
@@ -558,12 +558,8 @@ module AnnotateModels
       true
     end
 
-    def 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))/)
-    end
-
     def magic_comments_as_string(content)
-      magic_comments = content.scan(magic_comment_matcher).flatten.compact
+      magic_comments = content.scan(MAGIC_COMMENT_MATCHER).flatten.compact
 
       if magic_comments.any?
         magic_comments.join
@@ -902,13 +898,15 @@ module AnnotateModels
     end
 
     def max_schema_info_width(klass, options)
+      cols = columns(klass, options)
+
       if with_comments?(klass, options)
-        max_size = klass.columns.map do |column|
+        max_size = cols.map do |column|
           column.name.size + (column.comment ? width(column.comment) : 0)
         end.max || 0
         max_size += 2
       else
-        max_size = klass.column_names.map(&:size).max
+        max_size = cols.map(&:name).map(&:size).max
       end
       max_size += options[:format_rdoc] ? 5 : 1
 
@@ -920,7 +918,7 @@ module AnnotateModels
     end
 
     def width(string)
-      string.chars.inject(0) { |acc, elem| acc + (elem.bytesize == 1 ? 1 : 2) }
+      string.chars.inject(0) { |acc, elem| acc + (elem.bytesize == 3 ? 2 : 1) }
     end
 
     def mb_chars_ljust(string, length)
@@ -932,6 +930,72 @@ module AnnotateModels
         string[0..length-1]
       end
     end
+
+    def non_ascii_length(string)
+      string.to_s.chars.reject(&:ascii_only?).length
+    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 columns(klass, options)
+      cols = klass.columns
+      cols += translated_columns(klass)
+
+      if ignore_columns = options[: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
+
+    ##
+    # Add columns managed by the globalize gem if this gem is being used.
+    def translated_columns(klass)
+      return [] unless klass.respond_to? :translation_class
+
+      ignored_cols = ignored_translation_table_colums(klass)
+      klass.translation_class.columns.reject do |col|
+        ignored_cols.include? col.name.to_sym
+      end
+    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_colums(klass)
+      # 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
 
   class BadModelFileError < LoadError