annotaterb 4.0.0.beta.1

data/lib/annotate_rb/parser.rb

@@ -0,0 +1,385 @@
+require 'optparse'
+
+module AnnotateRb
+  # Class for handling command line arguments
+  class Parser # rubocop:disable Metrics/ClassLength
+    def self.parse(args, existing_options = {})
+      new(args, existing_options).parse
+    end
+
+    BANNER_STRING = <<~BANNER.freeze
+      Usage: annotaterb [command] [options]
+      
+      Commands:
+          models [options]
+          routes [options]
+          help
+          version
+    BANNER
+
+    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
+
+    COMMAND_MAP = {
+      'models' => :models,
+      'routes' => :routes,
+      'version' => :version,
+      'help' => :help
+    }.freeze
+
+    def initialize(args, existing_options)
+      @args = args
+      base_options = DEFAULT_OPTIONS.dup
+      @options = base_options.merge(existing_options)
+      @commands = []
+      @options[:original_args] = args.dup
+    end
+
+    def parse
+      parse_command(@args)
+
+      parser.parse!(@args)
+
+      act_on_command
+
+      @options
+    end
+
+    private
+
+    def parse_command(args)
+      command_arg = args.first
+      command = COMMAND_MAP[command_arg]
+
+      if command
+        args.shift
+        @commands << command
+      end
+    end
+
+    def act_on_command
+      map = {
+        models: Commands::AnnotateModels.new,
+        routes: Commands::AnnotateRoutes.new,
+        help: Commands::PrintHelp.new(@parser),
+        version: Commands::PrintVersion.new
+      }
+
+      if @commands.any?
+        @options[:command] = map[@commands.first]
+      elsif @commands.size > 1
+        # TODO: Should raise or alert user that multiple commands were selected but only 1 command will be ran
+        @options[:command] = map[@commands.first]
+      else # None
+        @options[:command] = nil
+      end
+    end
+
+    def parser
+      @parser ||= OptionParser.new do |option_parser|
+        option_parser.banner = BANNER_STRING
+
+        # ------------------------------------------------------------------------------------------------------------=
+        option_parser.separator('')
+        option_parser.separator('Options:')
+
+        option_parser.on('-v', '--version', "Display the version..") do
+          @commands << :version
+        end
+
+        option_parser.on('-h', '--help', "You're looking at it.") do
+          @commands << :help
+        end
+
+        add_model_options_to_parser(option_parser)
+        add_route_options_to_parser(option_parser)
+        add_wrapper_options_to_parser(option_parser)
+        add_options_to_parser(option_parser)
+        add_position_options_to_parser(option_parser)
+        add_utils_to_parser(option_parser)
+      end
+    end
+
+    def add_wrapper_options_to_parser(option_parser)
+      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|
+        @options[:wrapper] = wrapper
+      end
+
+      option_parser.on('--wo',
+                       '--wrapper-open STR',
+                       'Annotation wrapper opening.') do |wrapper_open|
+        @options[:wrapper_open] = wrapper_open
+      end
+
+      option_parser.on('--wc',
+                       '--wrapper-close STR',
+                       'Annotation wrapper closing') do |wrapper_close|
+        @options[:wrapper_close] = wrapper_close
+      end
+    end
+
+    def add_utils_to_parser(option_parser)
+      option_parser.on('--force',
+                       'Force new annotations even if there are no changes.') do
+        @options[:force] = true
+      end
+
+      option_parser.on('--debug',
+                       'Prints the options and outputs messages to make it easier to debug.') do
+        @options[:debug] = true
+      end
+
+      option_parser.on('--frozen',
+                       'Do not allow to change annotations. Exits non-zero if there are going to be changes to files.') do
+        @options[:frozen] = true
+      end
+
+      option_parser.on('--trace',
+                       'If unable to annotate a file, print the full stack trace, not just the exception message.') do
+        @options[:trace] = true
+      end
+    end
+
+    def add_model_options_to_parser(option_parser)
+      option_parser.separator('')
+      option_parser.separator('Annotate model options:')
+      option_parser.separator(' ' * 4 + 'Usage: annotaterb models [options]')
+      option_parser.separator('')
+
+      # option_parser.on('-m',
+      #                  '--models',
+      #                  "Annotate ActiveRecord models") do
+      #   @options[:models] = true
+      #   @options[:command] = Commands::AnnotateModels.new
+      # end
+
+      option_parser.on('-a',
+                       '--active-admin',
+                       'Annotate active_admin models') do
+        @options[:active_admin] = true
+      end
+
+      option_parser.on('--show-migration',
+                       'Include the migration version number in the annotation') do
+        @options[:include_version] = true
+      end
+
+      option_parser.on('-k',
+                       '--show-foreign-keys',
+                       "List the table's foreign key constraints in the annotation") do
+        @options[:show_foreign_keys] = true
+      end
+
+      option_parser.on('--ck',
+                       '--complete-foreign-keys',
+                       'Complete foreign key names in the annotation') do
+        @options[:show_foreign_keys] = true
+        @options[:show_complete_foreign_keys] = true
+      end
+
+      option_parser.on('-i',
+                       '--show-indexes',
+                       "List the table's database indexes in the annotation") do
+        @options[:show_indexes] = true
+      end
+
+      option_parser.on('-s',
+                       '--simple-indexes',
+                       "Concat the column's related indexes in the annotation") do
+        @options[:simple_indexes] = true
+      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|
+        @options[: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|
+        @options[:hide_default_column_types] = values.to_s
+      end
+
+      option_parser.on('--ignore-unknown-models',
+                       "don't display warnings for bad model files") do
+        @options[:ignore_unknown_models] = true
+      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|
+        @options[:ignore_columns] = regex
+      end
+
+      option_parser.on('--with-comment',
+                       "include database comments in model annotations") do
+        @options[:with_comment] = true
+      end
+    end
+
+    def add_route_options_to_parser(option_parser)
+      option_parser.separator('')
+      option_parser.separator('Annotate routes options:')
+      option_parser.separator(' ' * 4 + 'Usage: annotaterb routes [options]')
+      option_parser.separator('')
+
+      # option_parser.on('-r',
+      #                  '--routes',
+      #                  "Annotate routes.rb with the output of 'rails routes'") do
+      #   @options[:routes] = true
+      #   @options[:command] = Commands::AnnotateRoutes.new
+      # 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|
+        @options[:ignore_routes] = regex
+      end
+
+      option_parser.on('--timestamp',
+                       'Include timestamp in (routes) annotation') do
+        @options[:timestamp] = true
+      end
+    end
+
+    def add_position_options_to_parser(option_parser)
+      has_set_position = {}
+
+      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|
+        @options[:position] = position
+
+        FILE_TYPE_POSITIONS.each do |key|
+          @options[key.to_sym] = 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|
+        @options[: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|
+        @options[: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|
+        @options[: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|
+        @options[: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|
+        @options[: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|
+        @options[:position_in_serializer] = position_in_serializer
+        has_set_position['position_in_serializer'] = true
+      end
+    end
+
+    def add_options_to_parser(option_parser) # rubocop:disable Metrics/MethodLength
+      option_parser.separator('')
+      option_parser.separator('Command options:')
+      option_parser.separator('Additional options that work for annotating models and routes')
+      option_parser.separator('')
+
+      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|
+        @options[: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('--model-dir dir',
+                       "Annotate model files stored in dir rather than app/models, separate multiple dirs with commas") do |dir|
+        @options[:model_dir] = dir
+      end
+
+      option_parser.on('--root-dir dir',
+                       "Annotate files stored within root dir projects, separate multiple dirs with commas") do |dir|
+        @options[:root_dir] = dir
+      end
+
+      option_parser.on('--ignore-model-subdirects',
+                       "Ignore subdirectories of the models directory") do
+        @options[:ignore_model_sub_dir] = true
+      end
+
+      option_parser.on('--sort',
+                       "Sort columns alphabetically, rather than in creation order") do
+        @options[:sort] = true
+      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
+        @options[:classified_sort] = true
+      end
+
+      option_parser.on('-R',
+                       '--require path',
+                       "Additional file to require before loading models, may be used multiple times") do |path|
+        @options[:require] = if @options[:require].present?
+                           [@options[:require], path].join(',')
+                         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| @options["exclude_#{exclusion}".to_sym] = true }
+      end
+
+      option_parser.on('-f',
+                       '--format [bare|rdoc|yard|markdown]',
+                       FORMAT_TYPES,
+                       'Render Schema Information as plain/RDoc/Yard/Markdown') do |format_type|
+        @options["format_#{format_type}".to_sym] = true
+      end
+    end
+  end
+end

data/lib/annotate_rb/rake_bootstrapper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  class RakeBootstrapper
+    class << self
+      def call(options)
+        begin
+          require 'rake/dsl_definition'
+        rescue StandardError => e
+          # We might just be on an old version of Rake...
+          $stderr.puts e.message
+          exit e.status_code
+        end
+
+        require 'rake'
+        load './Rakefile' if File.exist?('./Rakefile')
+
+        begin
+          Rake::Task[:environment].invoke
+        rescue
+          nil
+        end
+
+        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
+      end
+    end
+  end
+end

data/lib/annotate_rb/route_annotator/annotation_processor.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# This module provides methods for annotating config/routes.rb.
+module AnnotateRb
+  module RouteAnnotator
+    # This class is abstract class of classes adding and removing annotation to config/routes.rb.
+    class AnnotationProcessor < BaseProcessor
+
+      # @return [String]
+      def execute
+        if routes_file_exist?
+          if update
+            "#{routes_file} was annotated."
+          else
+            "#{routes_file} was not changed."
+          end
+        else
+          "#{routes_file} could not be found."
+        end
+      end
+
+      private
+
+      def header
+        @header ||= HeaderGenerator.generate(options)
+      end
+
+      def generate_new_content_array(content, header_position)
+        magic_comments_map, content = Helper.extract_magic_comments_from_array(content)
+        if %w(before top).include?(options[:position_in_routes])
+          new_content_array = []
+          new_content_array += magic_comments_map
+          new_content_array << '' if magic_comments_map.any?
+          new_content_array += header
+          new_content_array << '' if content.first != ''
+          new_content_array += content
+        else
+          # Ensure we have adequate trailing newlines at the end of the file to
+          # ensure a blank line separating the content from the annotation.
+          content << '' unless content.last == ''
+
+          # We're moving something from the top of the file to the bottom, so ditch
+          # the spacer we put in the first time around.
+          content.shift if header_position == :before && content.first == ''
+
+          new_content_array = magic_comments_map + content + header
+        end
+
+        # Make sure we end on a trailing newline.
+        new_content_array << '' unless new_content_array.last == ''
+
+        new_content_array
+      end
+    end
+  end
+end

data/lib/annotate_rb/route_annotator/annotator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module RouteAnnotator
+    class Annotator
+      class << self
+        # TODO: Deprecate
+        def do_annotations(options = {})
+          add_annotations(options)
+        end
+
+        def add_annotations(options = {})
+          new(options).add_annotations
+        end
+
+        def remove_annotations(options = {})
+          new(options).remove_annotations
+        end
+      end
+
+      def initialize(options = {})
+        @options = options
+      end
+
+      def add_annotations
+        routes_file = File.join('config', 'routes.rb')
+        AnnotationProcessor.execute(@options, routes_file).tap do |result|
+          puts result
+        end
+      end
+
+      def remove_annotations
+        routes_file = File.join('config', 'routes.rb')
+        RemovalProcessor.execute(@options, routes_file).tap do |result|
+          puts result
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/route_annotator/base_processor.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# This module provides methods for annotating config/routes.rb.
+module AnnotateRb
+  module RouteAnnotator
+    # This class is abstract class of classes adding and removing annotation to config/routes.rb.
+    class BaseProcessor
+      class << self
+        # @param options [Hash]
+        # @param routes_file [String]
+        # @return [String]
+        def execute(options, routes_file)
+          new(options, routes_file).execute
+        end
+
+        private :new
+      end
+
+      def initialize(options, routes_file)
+        @options = options
+        @routes_file = routes_file
+      end
+
+      # @return [Boolean]
+      def update
+        if existing_text == new_text
+          false
+        else
+          write(new_text)
+          true
+        end
+      end
+
+      def routes_file_exist?
+        File.exist?(routes_file)
+      end
+
+      private
+
+      attr_reader :options, :routes_file
+
+      def generate_new_content_array(_content, _header_position)
+        raise NoMethodError
+      end
+
+      def existing_text
+        @existing_text ||= File.read(routes_file)
+      end
+
+      # @return [String]
+      def new_text
+        content, header_position = strip_annotations(existing_text)
+        new_content = generate_new_content_array(content, header_position)
+        new_content.join("\n")
+      end
+
+      def write(text)
+        File.open(routes_file, 'wb') { |f| f.puts(text) }
+      end
+
+      # TODO: write the method doc using ruby rdoc formats
+      # This method returns an array of 'real_content' and 'header_position'.
+      # 'header_position' will either be :before, :after, or
+      # a number.  If the number is > 0, the
+      # annotation was found somewhere in the
+      # middle of the file.  If the number is
+      # zero, no annotation was found.
+      def strip_annotations(content)
+        real_content = []
+        mode = :content
+        header_position = 0
+
+        content.split(/\n/, -1).each_with_index do |line, line_number|
+          if mode == :header && line !~ /\s*#/
+            mode = :content
+            real_content << line unless line.blank?
+          elsif mode == :content
+            if line =~ /^\s*#\s*== Route.*$/
+              header_position = line_number + 1 # index start's at 0
+              mode = :header
+            else
+              real_content << line
+            end
+          end
+        end
+
+        real_content_and_header_position(real_content, header_position)
+      end
+
+      def real_content_and_header_position(real_content, header_position)
+        # By default assume the annotation was found in the middle of the file
+
+        # ... unless we have evidence it was at the beginning ...
+        return real_content, :before if header_position == 1
+
+        # ... or that it was at the end.
+        return real_content, :after if header_position >= real_content.count
+
+        # and the default
+        return real_content, header_position
+      end
+    end
+  end
+end