annotate 2.7.4 → 3.1.1

data/lib/annotate/helpers.rb

@@ -0,0 +1,30 @@
+module Annotate
+  # Class for holding helper methods. Done to make lib/annotate.rb less bloated.
+  class Helpers
+    class << self
+      def skip_on_migration?
+        ENV['ANNOTATE_SKIP_ON_DB_MIGRATE'] =~ Constants::TRUE_RE || ENV['skip_on_db_migrate'] =~ Constants::TRUE_RE
+      end
+
+      def include_routes?
+        ENV['routes'] =~ Constants::TRUE_RE
+      end
+
+      def include_models?
+        ENV['models'] =~ Constants::TRUE_RE
+      end
+
+      def true?(val)
+        val.present? && Constants::TRUE_RE.match?(val)
+      end
+
+      def fallback(*args)
+        args.detect(&:present?)
+      end
+
+      def reset_options(options)
+        options.flatten.each { |key| ENV[key.to_s] = nil }
+      end
+    end
+  end
+end

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.7.4'
+    '3.1.1'
   end
 end

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

@@ -7,46 +7,51 @@ if Rails.env.development?
     # You can override any of these by setting an environment variable of the
     # same name.
     Annotate.set_defaults(
-      'routes'                    => 'false',
-      '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_markdown'           => 'false',
-      'sort'                      => 'false',
-      'force'                     => 'false',
-      'classified_sort'           => 'true',
-      'trace'                     => 'false',
-      'wrapper_open'              => nil,
-      'wrapper_close'             => nil,
-      'with_comment'              => true
+      '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
 

data/lib/tasks/annotate_models.rake

@@ -11,43 +11,47 @@ task annotate_models: :environment do
   require "#{annotate_lib}/annotate/active_record_patch"
 
   options = {is_rake: true}
-  ENV['position'] = options[:position] = Annotate.fallback(ENV['position'], 'before')
-  options[:position_in_class] = Annotate.fallback(ENV['position_in_class'], ENV['position'])
-  options[:position_in_fixture] = Annotate.fallback(ENV['position_in_fixture'], ENV['position'])
-  options[:position_in_factory] = Annotate.fallback(ENV['position_in_factory'], ENV['position'])
-  options[:position_in_test] = Annotate.fallback(ENV['position_in_test'], ENV['position'])
-  options[:position_in_serializer] = Annotate.fallback(ENV['position_in_serializer'], ENV['position'])
-  options[:show_foreign_keys] = Annotate.true?(ENV['show_foreign_keys'])
-  options[:show_complete_foreign_keys] = Annotate.true?(ENV['show_complete_foreign_keys'])
-  options[:show_indexes] = Annotate.true?(ENV['show_indexes'])
-  options[:simple_indexes] = Annotate.true?(ENV['simple_indexes'])
+  ENV['position'] = options[:position] = Annotate::Helpers.fallback(ENV['position'], 'before')
+  options[:additional_file_patterns] = ENV['additional_file_patterns'] ? ENV['additional_file_patterns'].split(',') : []
+  options[:position_in_class] = Annotate::Helpers.fallback(ENV['position_in_class'], ENV['position'])
+  options[:position_in_fixture] = Annotate::Helpers.fallback(ENV['position_in_fixture'], ENV['position'])
+  options[:position_in_factory] = Annotate::Helpers.fallback(ENV['position_in_factory'], ENV['position'])
+  options[:position_in_test] = Annotate::Helpers.fallback(ENV['position_in_test'], ENV['position'])
+  options[:position_in_serializer] = Annotate::Helpers.fallback(ENV['position_in_serializer'], ENV['position'])
+  options[:show_foreign_keys] = Annotate::Helpers.true?(ENV['show_foreign_keys'])
+  options[:show_complete_foreign_keys] = Annotate::Helpers.true?(ENV['show_complete_foreign_keys'])
+  options[:show_indexes] = Annotate::Helpers.true?(ENV['show_indexes'])
+  options[:simple_indexes] = Annotate::Helpers.true?(ENV['simple_indexes'])
   options[:model_dir] = ENV['model_dir'] ? ENV['model_dir'].split(',') : ['app/models']
   options[:root_dir] = ENV['root_dir']
-  options[:include_version] = Annotate.true?(ENV['include_version'])
+  options[:include_version] = Annotate::Helpers.true?(ENV['include_version'])
   options[:require] = ENV['require'] ? ENV['require'].split(',') : []
-  options[:exclude_tests] = Annotate.true?(ENV['exclude_tests'])
-  options[:exclude_factories] = Annotate.true?(ENV['exclude_factories'])
-  options[:exclude_fixtures] = Annotate.true?(ENV['exclude_fixtures'])
-  options[:exclude_serializers] = Annotate.true?(ENV['exclude_serializers'])
-  options[:exclude_scaffolds] = Annotate.true?(ENV['exclude_scaffolds'])
-  options[:exclude_controllers] = Annotate.true?(ENV.fetch('exclude_controllers', 'true'))
-  options[:exclude_helpers] = Annotate.true?(ENV.fetch('exclude_helpers', 'true'))
-  options[:exclude_sti_subclasses] = Annotate.true?(ENV['exclude_sti_subclasses'])
-  options[:ignore_model_sub_dir] = Annotate.true?(ENV['ignore_model_sub_dir'])
-  options[:format_bare] = Annotate.true?(ENV['format_bare'])
-  options[:format_rdoc] = Annotate.true?(ENV['format_rdoc'])
-  options[:format_markdown] = Annotate.true?(ENV['format_markdown'])
-  options[:sort] = Annotate.true?(ENV['sort'])
-  options[:force] = Annotate.true?(ENV['force'])
-  options[:classified_sort] = Annotate.true?(ENV['classified_sort'])
-  options[:trace] = Annotate.true?(ENV['trace'])
-  options[:wrapper_open] = Annotate.fallback(ENV['wrapper_open'], ENV['wrapper'])
-  options[:wrapper_close] = Annotate.fallback(ENV['wrapper_close'], ENV['wrapper'])
+  options[:exclude_tests] = Annotate::Helpers.true?(ENV['exclude_tests'])
+  options[:exclude_factories] = Annotate::Helpers.true?(ENV['exclude_factories'])
+  options[:exclude_fixtures] = Annotate::Helpers.true?(ENV['exclude_fixtures'])
+  options[:exclude_serializers] = Annotate::Helpers.true?(ENV['exclude_serializers'])
+  options[:exclude_scaffolds] = Annotate::Helpers.true?(ENV['exclude_scaffolds'])
+  options[:exclude_controllers] = Annotate::Helpers.true?(ENV.fetch('exclude_controllers', 'true'))
+  options[:exclude_helpers] = Annotate::Helpers.true?(ENV.fetch('exclude_helpers', 'true'))
+  options[:exclude_sti_subclasses] = Annotate::Helpers.true?(ENV['exclude_sti_subclasses'])
+  options[:ignore_model_sub_dir] = Annotate::Helpers.true?(ENV['ignore_model_sub_dir'])
+  options[:format_bare] = Annotate::Helpers.true?(ENV['format_bare'])
+  options[:format_rdoc] = Annotate::Helpers.true?(ENV['format_rdoc'])
+  options[:format_yard] = Annotate::Helpers.true?(ENV['format_yard'])
+  options[:format_markdown] = Annotate::Helpers.true?(ENV['format_markdown'])
+  options[:sort] = Annotate::Helpers.true?(ENV['sort'])
+  options[:force] = Annotate::Helpers.true?(ENV['force'])
+  options[:frozen] = Annotate::Helpers.true?(ENV['frozen'])
+  options[:classified_sort] = Annotate::Helpers.true?(ENV['classified_sort'])
+  options[:trace] = Annotate::Helpers.true?(ENV['trace'])
+  options[:wrapper_open] = Annotate::Helpers.fallback(ENV['wrapper_open'], ENV['wrapper'])
+  options[:wrapper_close] = Annotate::Helpers.fallback(ENV['wrapper_close'], ENV['wrapper'])
   options[:ignore_columns] = ENV.fetch('ignore_columns', nil)
   options[:ignore_routes] = ENV.fetch('ignore_routes', nil)
-  options[:hide_limit_column_types] = Annotate.fallback(ENV['hide_limit_column_types'], '')
-  options[:hide_default_column_types] = Annotate.fallback(ENV['hide_default_column_types'], '')
-  options[:with_comment] = Annotate.true?(ENV['with_comment'])
+  options[:hide_limit_column_types] = Annotate::Helpers.fallback(ENV['hide_limit_column_types'], '')
+  options[:hide_default_column_types] = Annotate::Helpers.fallback(ENV['hide_default_column_types'], '')
+  options[:with_comment] = Annotate::Helpers.true?(ENV['with_comment'])
+  options[:ignore_unknown_models] = Annotate::Helpers.true?(ENV.fetch('ignore_unknown_models', 'false'))
 
   AnnotateModels.do_annotations(options)
 end
@@ -61,6 +65,6 @@ task remove_annotation: :environment do
   options[:model_dir] = ENV['model_dir']
   options[:root_dir] = ENV['root_dir']
   options[:require] = ENV['require'] ? ENV['require'].split(',') : []
-  options[:trace] = Annotate.true?(ENV['trace'])
+  options[:trace] = Annotate::Helpers.true?(ENV['trace'])
   AnnotateModels.remove_annotations(options)
 end