annotate 2.6.3 → 3.2.0

data/lib/annotate/parser.rb

@@ -0,0 +1,303 @@
+require 'optparse'
+
+module Annotate
+  # Class for handling command line arguments
+  class Parser # rubocop:disable Metrics/ClassLength
+    def self.parse(args, env = {})
+      new(args, env).parse
+    end
+
+    attr_reader :args, :options, :env
+
+    DEFAULT_OPTIONS = {
+      target_action: :do_annotations,
+      exit: false
+    }.freeze
+
+    ANNOTATION_POSITIONS = %w[before top after bottom].freeze
+    FILE_TYPE_POSITIONS = %w[position_in_class position_in_factory position_in_fixture position_in_test position_in_routes position_in_serializer].freeze
+    EXCLUSION_LIST = %w[tests fixtures factories serializers].freeze
+    FORMAT_TYPES = %w[bare rdoc yard markdown].freeze
+
+    def initialize(args, env)
+      @args = args
+      @options = DEFAULT_OPTIONS.dup
+      @env = env
+    end
+
+    def parse
+      # To split up because right now this method parses and commits
+      parser.parse!(args)
+
+      commit
+
+      options
+    end
+
+    private
+
+    def parser
+      OptionParser.new do |option_parser|
+        add_options_to_parser(option_parser)
+      end
+    end
+
+    def commit
+      env.each_pair do |key, value|
+        ENV[key] = value
+      end
+    end
+
+    def add_options_to_parser(option_parser) # rubocop:disable Metrics/MethodLength
+      has_set_position = {}
+
+      option_parser.banner = 'Usage: annotate [options] [model_file]*'
+
+      option_parser.on('--additional-file-patterns path1,path2,path3',
+                       Array,
+                       "Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)") do |additional_file_patterns|
+        ENV['additional_file_patterns'] = additional_file_patterns
+      end
+
+      option_parser.on('-d',
+                       '--delete',
+                       'Remove annotations from all model files or the routes.rb file') do
+        @options[:target_action] = :remove_annotations
+      end
+
+      option_parser.on('-p',
+                       '--position [before|top|after|bottom]',
+                       ANNOTATION_POSITIONS,
+                       'Place the annotations at the top (before) or the bottom (after) of the model/test/fixture/factory/route/serializer file(s)') do |position|
+        env['position'] = position
+
+        FILE_TYPE_POSITIONS.each do |key|
+          env[key] = position unless has_set_position[key]
+        end
+      end
+
+      option_parser.on('--pc',
+                       '--position-in-class [before|top|after|bottom]',
+                       ANNOTATION_POSITIONS,
+                       'Place the annotations at the top (before) or the bottom (after) of the model file') do |position_in_class|
+        env['position_in_class'] = position_in_class
+        has_set_position['position_in_class'] = true
+      end
+
+      option_parser.on('--pf',
+                       '--position-in-factory [before|top|after|bottom]',
+                       ANNOTATION_POSITIONS,
+                       'Place the annotations at the top (before) or the bottom (after) of any factory files') do |position_in_factory|
+        env['position_in_factory'] = position_in_factory
+        has_set_position['position_in_factory'] = true
+      end
+
+      option_parser.on('--px',
+                       '--position-in-fixture [before|top|after|bottom]',
+                       ANNOTATION_POSITIONS,
+                       'Place the annotations at the top (before) or the bottom (after) of any fixture files') do |position_in_fixture|
+        env['position_in_fixture'] = position_in_fixture
+        has_set_position['position_in_fixture'] = true
+      end
+
+      option_parser.on('--pt',
+                       '--position-in-test [before|top|after|bottom]',
+                       ANNOTATION_POSITIONS,
+                       'Place the annotations at the top (before) or the bottom (after) of any test files') do |position_in_test|
+        env['position_in_test'] = position_in_test
+        has_set_position['position_in_test'] = true
+      end
+
+      option_parser.on('--pr',
+                       '--position-in-routes [before|top|after|bottom]',
+                       ANNOTATION_POSITIONS,
+                       'Place the annotations at the top (before) or the bottom (after) of the routes.rb file') do |position_in_routes|
+        env['position_in_routes'] = position_in_routes
+        has_set_position['position_in_routes'] = true
+      end
+
+      option_parser.on('--ps',
+                       '--position-in-serializer [before|top|after|bottom]',
+                       ANNOTATION_POSITIONS,
+                       'Place the annotations at the top (before) or the bottom (after) of the serializer files') do |position_in_serializer|
+        env['position_in_serializer'] = position_in_serializer
+        has_set_position['position_in_serializer'] = true
+      end
+
+      option_parser.on('--w',
+                       '--wrapper STR',
+                       'Wrap annotation with the text passed as parameter.',
+                       'If --w option is used, the same text will be used as opening and closing') do |wrapper|
+        env['wrapper'] = wrapper
+      end
+
+      option_parser.on('--wo',
+                       '--wrapper-open STR',
+                       'Annotation wrapper opening.') do |wrapper_open|
+        env['wrapper_open'] = wrapper_open
+      end
+
+      option_parser.on('--wc',
+                       '--wrapper-close STR',
+                       'Annotation wrapper closing') do |wrapper_close|
+        env['wrapper_close'] = wrapper_close
+      end
+
+      option_parser.on('-r',
+                       '--routes',
+                       "Annotate routes.rb with the output of 'rake routes'") do
+        env['routes'] = 'true'
+      end
+
+      option_parser.on('--models',
+                       "Annotate ActiveRecord models") do
+        env['models'] = 'true'
+      end
+
+      option_parser.on('-a',
+                       '--active-admin',
+                       'Annotate active_admin models') do
+        env['active_admin'] = 'true'
+      end
+
+      option_parser.on('-v',
+                       '--version',
+                       'Show the current version of this gem') do
+        puts "annotate v#{Annotate.version}"
+        @options[:exit] = true
+      end
+
+      option_parser.on('-m',
+                       '--show-migration',
+                       'Include the migration version number in the annotation') do
+        env['include_version'] = 'yes'
+      end
+
+      option_parser.on('-k',
+                       '--show-foreign-keys',
+                       "List the table's foreign key constraints in the annotation") do
+        env['show_foreign_keys'] = 'yes'
+      end
+
+      option_parser.on('--ck',
+                       '--complete-foreign-keys',
+                       'Complete foreign key names in the annotation') do
+        env['show_foreign_keys'] = 'yes'
+        env['show_complete_foreign_keys'] = 'yes'
+      end
+
+      option_parser.on('-i',
+                       '--show-indexes',
+                       "List the table's database indexes in the annotation") do
+        env['show_indexes'] = 'yes'
+      end
+
+      option_parser.on('-s',
+                       '--simple-indexes',
+                       "Concat the column's related indexes in the annotation") do
+        env['simple_indexes'] = 'yes'
+      end
+
+      option_parser.on('--model-dir dir',
+                       "Annotate model files stored in dir rather than app/models, separate multiple dirs with commas") do |dir|
+        env['model_dir'] = dir
+      end
+
+      option_parser.on('--root-dir dir',
+                       "Annotate files stored within root dir projects, separate multiple dirs with commas") do |dir|
+        env['root_dir'] = dir
+      end
+
+      option_parser.on('--ignore-model-subdirects',
+                       "Ignore subdirectories of the models directory") do
+        env['ignore_model_sub_dir'] = 'yes'
+      end
+
+      option_parser.on('--sort',
+                       "Sort columns alphabetically, rather than in creation order") do
+        env['sort'] = 'yes'
+      end
+
+      option_parser.on('--classified-sort',
+                       "Sort columns alphabetically, but first goes id, then the rest columns, then the timestamp columns and then the association columns") do
+        env['classified_sort'] = 'yes'
+      end
+
+      option_parser.on('-R',
+                       '--require path',
+                       "Additional file to require before loading models, may be used multiple times") do |path|
+        env['require'] = if env['require'].present?
+                           "#{env['require']},#{path}"
+                         else
+                           path
+                         end
+      end
+
+      option_parser.on('-e',
+                       '--exclude [tests,fixtures,factories,serializers]',
+                       Array,
+                       "Do not annotate fixtures, test files, factories, and/or serializers") do |exclusions|
+        exclusions ||= EXCLUSION_LIST
+        exclusions.each { |exclusion| env["exclude_#{exclusion}"] = 'yes' }
+      end
+
+      option_parser.on('-f',
+                       '--format [bare|rdoc|yard|markdown]',
+                       FORMAT_TYPES,
+                       'Render Schema Infomation as plain/RDoc/Yard/Markdown') do |format_type|
+        env["format_#{format_type}"] = 'yes'
+      end
+
+      option_parser.on('--force',
+                       'Force new annotations even if there are no changes.') do
+        env['force'] = 'yes'
+      end
+
+      option_parser.on('--frozen',
+                       'Do not allow to change annotations. Exits non-zero if there are going to be changes to files.') do
+        env['frozen'] = 'yes'
+      end
+
+      option_parser.on('--timestamp',
+                       'Include timestamp in (routes) annotation') do
+        env['timestamp'] = 'true'
+      end
+
+      option_parser.on('--trace',
+                       'If unable to annotate a file, print the full stack trace, not just the exception message.') do
+        env['trace'] = 'yes'
+      end
+
+      option_parser.on('-I',
+                       '--ignore-columns REGEX',
+                       "don't annotate columns that match a given REGEX (i.e., `annotate -I '^(id|updated_at|created_at)'`") do |regex|
+        env['ignore_columns'] = regex
+      end
+
+      option_parser.on('--ignore-routes REGEX',
+                       "don't annotate routes that match a given REGEX (i.e., `annotate -I '(mobile|resque|pghero)'`") do |regex|
+        env['ignore_routes'] = regex
+      end
+
+      option_parser.on('--hide-limit-column-types VALUES',
+                       "don't show limit for given column types, separated by commas (i.e., `integer,boolean,text`)") do |values|
+        env['hide_limit_column_types'] = values.to_s
+      end
+
+      option_parser.on('--hide-default-column-types VALUES',
+                       "don't show default for given column types, separated by commas (i.e., `json,jsonb,hstore`)") do |values|
+        env['hide_default_column_types'] = values.to_s
+      end
+
+      option_parser.on('--ignore-unknown-models',
+                       "don't display warnings for bad model files") do
+        env['ignore_unknown_models'] = 'true'
+      end
+
+      option_parser.on('--with-comment',
+                       "include database comments in model annotations") do
+        env['with_comment'] = 'true'
+      end
+    end
+  end
+end

data/lib/annotate/version.rb

@@ -1,5 +1,5 @@
 module Annotate
   def self.version
-    '2.6.3'
+    '3.2.0'
   end
 end

data/lib/annotate.rb

@@ -1,103 +1,92 @@
-$:.unshift(File.dirname(__FILE__))
+$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...
   require 'active_support/hash_with_indifferent_access'
-rescue Exception => e
+  require 'active_support/core_ext/object/blank'
+rescue StandardError
   # ActiveSupport 2.x...
   require 'active_support/core_ext/hash/indifferent_access'
+  require 'active_support/core_ext/blank'
 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,
-  ]
-  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, :trace,
-  ]
-  OTHER_OPTIONS=[
-    :model_dir, :ignore_columns
-  ]
-  PATH_OPTIONS=[
-    :require,
-  ]
-
-
   ##
   # Set default values that can be overridden via environment variables.
   #
   def self.set_defaults(options = {})
-    return if(@has_set_defaults)
+    return if @has_set_defaults
     @has_set_defaults = true
-    options = HashWithIndifferentAccess.new(options)
-    [POSITION_OPTIONS, FLAG_OPTIONS, PATH_OPTIONS].flatten.each do |key|
-      if(options.has_key?(key))
-        default_value = if(options[key].is_a?(Array))
-          options[key].join(",")
-        else
-          options[key]
-        end
+
+    options = ActiveSupport::HashWithIndifferentAccess.new(options)
+
+    Constants::ALL_ANNOTATE_OPTIONS.flatten.each do |key|
+      if options.key?(key)
+        default_value = if options[key].is_a?(Array)
+                          options[key].join(',')
+                        else
+                          options[key]
+                        end
       end
-      default_value = ENV[key.to_s] if(!ENV[key.to_s].blank?)
-      ENV[key.to_s] = default_value.to_s
+
+      default_value = ENV[key.to_s] unless ENV[key.to_s].blank?
+      ENV[key.to_s] = default_value.nil? ? nil : default_value.to_s
     end
   end
 
-  TRUE_RE = /^(true|t|yes|y|1)$/i
+  ##
+  # 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|
-      options[key] = (!ENV[key.to_s].blank?) ? ENV[key.to_s] : nil
+    Constants::OTHER_OPTIONS.each do |key|
+      options[key] = !ENV[key.to_s].blank? ? ENV[key.to_s] : nil
     end
-    PATH_OPTIONS.each do |key|
-      options[key] = (!ENV[key.to_s].blank?) ? ENV[key.to_s].split(',') : []
+    Constants::PATH_OPTIONS.each do |key|
+      options[key] = !ENV[key.to_s].blank? ? ENV[key.to_s].split(',') : []
     end
 
-    if(!options[:model_dir])
-      options[:model_dir] = 'app/models'
-    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?
 
-    return options
-  end
+    options[:wrapper_open] ||= options[:wrapper]
+    options[:wrapper_close] ||= options[:wrapper]
 
-  def self.skip_on_migration?
-    ENV['skip_on_db_migrate'] =~ TRUE_RE
-  end
+    # These were added in 2.7.0 but so this is to revert to old behavior by default
+    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'))
 
-  def self.loaded_tasks=(val); @loaded_tasks = val; end
-  def self.loaded_tasks; return @loaded_tasks; end
+    options
+  end
 
   def self.load_tasks
-    return if(self.loaded_tasks)
-    self.loaded_tasks = true
+    return if @tasks_loaded
 
-    Dir[File.join(File.dirname(__FILE__), 'tasks', '**/*.rake')].each { |rake| load rake }
-  end
+    Dir[File.join(File.dirname(__FILE__), 'tasks', '**/*.rake')].each do |rake|
+      load rake
+    end
 
-  def self.load_requires(options)
-    options[:require].each { |path| require path } if options[:require].count > 0
+    @tasks_loaded = true
   end
 
   def self.eager_load(options)
-    self.load_requires(options)
-    require "annotate/active_record_patch"
+    load_requires(options)
+    require 'annotate/active_record_patch'
 
-    if(defined?(Rails))
-      if(Rails.version.split('.').first.to_i < 3)
+    if defined?(Rails::Application)
+      if Rails.version.split('.').first.to_i < 3
         Rails.configuration.eager_load_paths.each do |load_path|
           matcher = /\A#{Regexp.escape(load_path)}(.*)\.rb\Z/
           Dir.glob("#{load_path}/**/*.rb").sort.each do |file|
@@ -109,8 +98,10 @@ module Annotate
         klass.eager_load!
       end
     else
-      FileList["#{options[:model_dir]}/**/*.rb"].each do |fname|
-        require File.expand_path(fname)
+      options[:model_dir].each do |dir|
+        FileList["#{dir}/**/*.rb"].each do |fname|
+          require File.expand_path(fname)
+        end
       end
     end
   end
@@ -118,33 +109,37 @@ module Annotate
   def self.bootstrap_rake
     begin
       require 'rake/dsl_definition'
-    rescue Exception => e
+    rescue StandardError => e
       # We might just be on an old version of Rake...
+      $stderr.puts e.message
+      exit e.status_code
     end
     require 'rake'
 
-    if File.exists?('./Rakefile')
-      load './Rakefile'
+    load './Rakefile' if File.exist?('./Rakefile')
+    begin
+      Rake::Task[:environment].invoke
+    rescue
+      nil
     end
-    Rake::Task[:environment].invoke rescue nil
-    if(!defined?(Rails))
+    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
-    self.load_tasks
+
+    load_tasks
     Rake::Task[:set_annotation_options].invoke
   end
 
-  def self.fallback(*args)
-    return args.detect { |arg| !arg.blank? }
-  end
+  class << self
+    private
 
-  def self.true?(val)
-    return false if(val.blank?)
-    return false unless(val =~ TRUE_RE)
-    return true
+    def load_requires(options)
+      options[:require].count > 0 &&
+        options[:require].each { |path| require path }
+    end
   end
 end

data/lib/generators/annotate/install_generator.rb

@@ -1,14 +1,15 @@
+require 'annotate'
+
 module Annotate
   module Generators
     class InstallGenerator < Rails::Generators::Base
-      desc "Copy annotate_models rakefiles for automatic annotation"
-      source_root File.expand_path('../templates', __FILE__)
+      desc 'Copy annotate_models rakefiles for automatic annotation'
+      source_root File.expand_path('templates', __dir__)
 
       # copy rake tasks
       def copy_tasks
-        template "auto_annotate_models.rake", "lib/tasks/auto_annotate_models.rake"
+        template 'auto_annotate_models.rake', 'lib/tasks/auto_annotate_models.rake'
       end
-
     end
   end
 end

data/lib/generators/annotate/templates/auto_annotate_models.rake

@@ -1,33 +1,58 @@
 # NOTE: only doing this in development as some production environments (Heroku)
 # NOTE: are sensitive to local FS writes, and besides -- it's just not proper
 # NOTE: to have a dev-mode tool do its thing in production.
-if(Rails.env.development?)
+if Rails.env.development?
+  require 'annotate'
   task :set_annotation_options do
     # You can override any of these by setting an environment variable of the
     # same name.
-    Annotate.set_defaults({
-      'position_in_routes'   => "before",
-      'position_in_class'    => "before",
-      'position_in_test'     => "before",
-      'position_in_fixture'  => "before",
-      'position_in_factory'  => "before",
-      'show_indexes'         => "true",
-      'simple_indexes'       => "false",
-      'model_dir'            => "app/models",
-      'include_version'      => "false",
-      'require'              => "",
-      'exclude_tests'        => "false",
-      'exclude_fixtures'     => "false",
-      'exclude_factories'    => "false",
-      'ignore_model_sub_dir' => "false",
-      'skip_on_db_migrate'   => "false",
-      'format_bare'          => "true",
-      'format_rdoc'          => "false",
-      'format_markdown'      => "false",
-      'sort'                 => "false",
-      'force'                => "false",
-      'trace'                => "false",
-    })
+    Annotate.set_defaults(
+      'active_admin'                => 'false',
+      'additional_file_patterns'    => [],
+      'routes'                      => 'false',
+      'models'                      => 'true',
+      'position_in_routes'          => 'before',
+      'position_in_class'           => 'before',
+      'position_in_test'            => 'before',
+      'position_in_fixture'         => 'before',
+      'position_in_factory'         => 'before',
+      'position_in_serializer'      => 'before',
+      'show_foreign_keys'           => 'true',
+      'show_complete_foreign_keys'  => 'false',
+      'show_indexes'                => 'true',
+      'simple_indexes'              => 'false',
+      'model_dir'                   => 'app/models',
+      'root_dir'                    => '',
+      'include_version'             => 'false',
+      'require'                     => '',
+      'exclude_tests'               => 'false',
+      'exclude_fixtures'            => 'false',
+      'exclude_factories'           => 'false',
+      'exclude_serializers'         => 'false',
+      'exclude_scaffolds'           => 'true',
+      'exclude_controllers'         => 'true',
+      'exclude_helpers'             => 'true',
+      'exclude_sti_subclasses'      => 'false',
+      'ignore_model_sub_dir'        => 'false',
+      'ignore_columns'              => nil,
+      'ignore_routes'               => nil,
+      'ignore_unknown_models'       => 'false',
+      'hide_limit_column_types'     => '<%= AnnotateModels::NO_LIMIT_COL_TYPES.join(",") %>',
+      'hide_default_column_types'   => '<%= AnnotateModels::NO_DEFAULT_COL_TYPES.join(",") %>',
+      'skip_on_db_migrate'          => 'false',
+      'format_bare'                 => 'true',
+      'format_rdoc'                 => 'false',
+      'format_yard'                 => 'false',
+      'format_markdown'             => 'false',
+      'sort'                        => 'false',
+      'force'                       => 'false',
+      'frozen'                      => 'false',
+      'classified_sort'             => 'true',
+      'trace'                       => 'false',
+      'wrapper_open'                => nil,
+      'wrapper_close'               => nil,
+      'with_comment'                => 'true'
+    )
   end
 
   Annotate.load_tasks