annotaterb 4.0.0.beta.1 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ca3a25c118bfa3f5910e4fe455de3d9333c353d409f434cffde12694f87cff5
-  data.tar.gz: 417dcf943056ec0f44ba7eb973c3ad2dc99cb435315d41a13d1fc9f53bb87b9e
+  metadata.gz: 1c77ca5a809b63c94e69b937732b8f8f531807cc332627791b649576e8ed583e
+  data.tar.gz: c2fb3ac84bad2e0cd108c801ca162a6a17b34ba800af8f5e885e03c8338d636d
 SHA512:
-  metadata.gz: 2d34ca80e5686ef6cadfe0a2624aecd891fde3628653e68fa8b86613ac6382a4d7bdcf8e0c7504988dd653023be3d1190c5a072d46890b9c874ecaf1abbc20f7
-  data.tar.gz: 2ae8ca4a18c83437b379f7823291c094a87db9465742bf2c1c94c99fcfe1cb833f894367774a44ff2a9e7c8f41f9670f8baeedff1d5832bbbf2c49a6ced8ac80
+  metadata.gz: fb88fa8b511e0ccbbadce0db7d0ae941234967eb7358fea1146e48309939b1b35e51f8db9f15d544a6af4b3827decb65e51f4546d73feb2ab2f404c67f3c0f05
+  data.tar.gz: 562cd430feba785e8f53ab90f79dfa1c3765f46a8e048bbe379955c8f696dd4e01ce167245cf17e31de4704dc0e22da859cba2f6f00c87d10782e637c2faad65

data/README.md

@@ -1,8 +1,11 @@
 ## AnnotateRb
 ### forked from the [Annotate aka AnnotateModels gem](https://github.com/ctran/annotate_models)
 
+A Ruby Gem that adds annotations to your Rails models and route files.
+
 ----------
 [![CI](https://github.com/drwl/annotaterb/actions/workflows/ci.yml/badge.svg)](https://github.com/drwl/annotaterb/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/annotaterb.svg)](https://badge.fury.io/rb/annotaterb)
 
 Adds comments summarizing the model schema or routes in your:
 
@@ -57,8 +60,10 @@ $ bin/rails g annotate_rb:install
 This will copy a rake task into your Rails project's `lib/tasks` directory that will hook into the Rails project rake tasks, automatically running AnnotateRb after database migration rake tasks.
 
 ## Migrating from the annotate gem
+The old [annotate gem](https://github.com/ctran/annotate_models) relied on environment variables and hardcoded values in rake files for configuration. AnnotateRb is different. It reads from an optional configuration yml file and options from the CLI to function.
 
-Add steps for migrating from annotate gem.
+* Remove the following files `lib/tasks/annotate_models.rake`, `lib/tasks/annotate_models_migrate.rake`, `lib/tasks/annotate_routes.rake`.
+* Run the generator install command above.
 
 ## Usage
 
@@ -67,10 +72,95 @@ AnnotateRb has a CLI that you can use to add or remove annotations.
 ```sh
 # To show the CLI options
 $ bundle exec annotaterb 
+
+Usage: annotaterb [command] [options]
+
+Commands:
+    models [options]
+    routes [options]
+    help
+    version
+
+Options:
+    -v, --version                    Display the version..
+    -h, --help                       You're looking at it.
+
+Annotate model options:
+    Usage: annotaterb models [options]
+
+    -a, --active-admin               Annotate active_admin models
+        --show-migration             Include the migration version number in the annotation
+    -k, --show-foreign-keys          List the table's foreign key constraints in the annotation
+        --ck, --complete-foreign-keys
+                                     Complete foreign key names in the annotation
+    -i, --show-indexes               List the table's database indexes in the annotation
+    -s, --simple-indexes             Concat the column's related indexes in the annotation
+        --hide-limit-column-types VALUES
+                                     don't show limit for given column types, separated by commas (i.e., `integer,boolean,text`)
+        --hide-default-column-types VALUES
+                                     don't show default for given column types, separated by commas (i.e., `json,jsonb,hstore`)
+        --ignore-unknown-models      don't display warnings for bad model files
+    -I, --ignore-columns REGEX       don't annotate columns that match a given REGEX (i.e., `annotate -I '^(id|updated_at|created_at)'`
+        --with-comment               include database comments in model annotations
+
+Annotate routes options:
+    Usage: annotaterb routes [options]
+
+        --ignore-routes REGEX        don't annotate routes that match a given REGEX (i.e., `annotate -I '(mobile|resque|pghero)'`
+        --timestamp                  Include timestamp in (routes) annotation
+        --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
+        --wo, --wrapper-open STR     Annotation wrapper opening.
+        --wc, --wrapper-close STR    Annotation wrapper closing
+
+Command options:
+Additional options that work for annotating models and routes
+
+        --additional-file-patterns path1,path2,path3
+                                     Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)
+    -d, --delete                     Remove annotations from all model files or the routes.rb file
+        --model-dir dir              Annotate model files stored in dir rather than app/models, separate multiple dirs with commas
+        --root-dir dir               Annotate files stored within root dir projects, separate multiple dirs with commas
+        --ignore-model-subdirects    Ignore subdirectories of the models directory
+        --sort                       Sort columns alphabetically, rather than in creation order
+        --classified-sort            Sort columns alphabetically, but first goes id, then the rest columns, then the timestamp columns and then the association columns
+    -R, --require path               Additional file to require before loading models, may be used multiple times
+    -e [tests,fixtures,factories,serializers],
+        --exclude                    Do not annotate fixtures, test files, factories, and/or serializers
+    -f [bare|rdoc|yard|markdown],    Render Schema Information as plain/RDoc/Yard/Markdown
+        --format
+    -p [before|top|after|bottom],    Place the annotations at the top (before) or the bottom (after) of the model/test/fixture/factory/route/serializer file(s)
+        --position
+        --pc, --position-in-class [before|top|after|bottom]
+                                     Place the annotations at the top (before) or the bottom (after) of the model file
+        --pf, --position-in-factory [before|top|after|bottom]
+                                     Place the annotations at the top (before) or the bottom (after) of any factory files
+        --px, --position-in-fixture [before|top|after|bottom]
+                                     Place the annotations at the top (before) or the bottom (after) of any fixture files
+        --pt, --position-in-test [before|top|after|bottom]
+                                     Place the annotations at the top (before) or the bottom (after) of any test files
+        --pr, --position-in-routes [before|top|after|bottom]
+                                     Place the annotations at the top (before) or the bottom (after) of the routes.rb file
+        --ps, --position-in-serializer [before|top|after|bottom]
+                                     Place the annotations at the top (before) or the bottom (after) of the serializer files
+        --force                      Force new annotations even if there are no changes.
+        --debug                      Prints the options and outputs messages to make it easier to debug.
+        --frozen                     Do not allow to change annotations. Exits non-zero if there are going to be changes to files.
+        --trace                      If unable to annotate a file, print the full stack trace, not just the exception message.
 ```
 
 ## Configuration
 
+### Storing default options
+Previously in the [Annotate](https://github.com/ctran/annotate_models) you could pass options through the CLI or store them as environment variables. Annotaterb removes dependency on the environment variables and instead can read values from a `.annotaterb.yml` file stored in the Rails project root.
+
+```yml
+# .annotaterb.yml
+
+position: after
+```
+
+Annotaterb reads first from the configuration file, if it exists, then merges it with any options passed into the CLI.
 
 ### How to skip annotating a particular model
 If you want to always skip annotations on a particular model, add this string

data/VERSION

@@ -1 +1 @@
-4.0.0.beta.1
+4.1.0

data/lib/annotate_rb/model_annotator/annotation_decider.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    # Class that encapsulates the logic to decide whether to annotate a model file and its related files or not.
+    class AnnotationDecider
+      def initialize(file, options)
+        @file = file
+        @options = options
+      end
+
+      def annotate?
+        return false if file_contains_skip_annotation
+
+        begin
+          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.respond_to?(:abstract_class) && !klass.abstract_class?
+          klass_table_exists = klass.respond_to?(:abstract_class) && 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
+          ]
+
+          to_annotate = annotate_conditions.all?
+
+          return to_annotate
+        rescue BadModelFileError => e
+          unless @options[:ignore_unknown_models]
+            $stderr.puts "Unable to annotate #{@file}: #{e.message}"
+            $stderr.puts "\t" + e.backtrace.join("\n\t") if @options[:trace]
+          end
+        rescue StandardError => e
+          $stderr.puts "Unable to annotate #{@file}: #{e.message}"
+          $stderr.puts "\t" + e.backtrace.join("\n\t") if @options[:trace]
+        end
+
+        false
+      end
+
+      private
+
+      def file_contains_skip_annotation
+        file_string = File.exist?(@file) ? File.read(@file) : ''
+
+        if /#{Constants::SKIP_ANNOTATION_PREFIX}.*/ =~ file_string
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/annotation_generator.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class AnnotationGenerator
+      # Annotate Models plugin use this header
+      PREFIX = '== Schema Information'.freeze
+      PREFIX_MD = '## Schema Information'.freeze
+
+      END_MARK = '== Schema Information End'.freeze
+
+      MD_NAMES_OVERHEAD = 6
+      MD_TYPE_ALLOWANCE = 18
+
+      def initialize(klass, options = {})
+        @model = ModelWrapper.new(klass, options)
+        @options = options
+        @info = "" # TODO: Make array and build string that way
+      end
+
+      def generate
+        @info = "# #{header}\n"
+        @info += schema_header_text
+
+        max_size = @model.max_schema_info_width
+
+        if @options[:format_markdown]
+          @info += format("# %-#{max_size + MD_NAMES_OVERHEAD}.#{max_size + MD_NAMES_OVERHEAD}s | %-#{MD_TYPE_ALLOWANCE}.#{MD_TYPE_ALLOWANCE}s | %s\n",
+                          'Name',
+                          'Type',
+                          'Attributes')
+          @info += "# #{'-' * (max_size + MD_NAMES_OVERHEAD)} | #{'-' * MD_TYPE_ALLOWANCE} | #{'-' * 27}\n"
+        end
+
+        @info += @model.columns.map do |col|
+          ColumnAnnotationBuilder.new(col, @model, max_size, @options).build
+        end.join
+
+        if @options[:show_indexes] && @model.table_exists?
+          @info += IndexAnnotationBuilder.new(@model, @options).build
+        end
+
+        if @options[:show_foreign_keys] && @model.table_exists?
+          @info += ForeignKeyAnnotationBuilder.new(@model, @options).build
+        end
+
+        @info += schema_footer_text
+
+        @info
+      end
+
+      def header
+        header = @options[:format_markdown] ? PREFIX_MD.dup : PREFIX.dup
+        version = ActiveRecord::Migrator.current_version rescue 0
+
+        if @options[:include_version] && version > 0
+          header += "\n# Schema version: #{version}"
+        end
+
+        header
+      end
+
+      def schema_header_text
+        info = []
+        info << "#"
+
+        if @options[:format_markdown]
+          info << "# Table name: `#{@model.table_name}`"
+          info << "#"
+          info << "# ### Columns"
+        else
+          info << "# Table name: #{@model.table_name}"
+        end
+        info << "#\n" # We want the last line break
+
+        info.join("\n")
+      end
+
+      def schema_footer_text
+        info = []
+
+        if @options[:format_rdoc]
+          info << "#--"
+          info << "# #{END_MARK}"
+          info << "#++\n"
+        else
+          info << "#\n"
+        end
+
+        info.join("\n")
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/annotator.rb

@@ -1,31 +1,20 @@
-# require 'bigdecimal'
+# frozen_string_literal: true
 
 module AnnotateRb
   module ModelAnnotator
     class Annotator
-      # Annotate Models plugin use this header
-      PREFIX = '== Schema Information'.freeze
-      PREFIX_MD = '## Schema Information'.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
-        # We're passed a name of things that might be
-        # ActiveRecord models. If we can find the class, and
-        # if its a subclass of ActiveRecord::Base,
-        # then pass it to the associated block
         def do_annotations(options = {})
-          header = options[:format_markdown] ? PREFIX_MD.dup : PREFIX.dup
-          version = ActiveRecord::Migrator.current_version rescue 0
-          if options[:include_version] && version > 0
-            header << "\n# Schema version: #{version}"
-          end
-
           annotated = []
-          model_files_to_annotate = ModelFilesGetter.call(options)
 
-          model_files_to_annotate.each do |path, filename|
-            ModelFileAnnotator.call(annotated, File.join(path, filename), header, options)
+          model_files_to_consider = ModelFilesGetter.call(options)
+
+          model_files_to_consider.each do |path, filename|
+            file = File.join(path, filename)
+
+            if AnnotationDecider.new(file, options).annotate?
+              ModelFileAnnotator.call(annotated, file, options)
+            end
           end
 
           if annotated.empty?
@@ -37,34 +26,41 @@ module AnnotateRb
 
         def remove_annotations(options = {})
           deannotated = []
-          deannotated_klass = false
-          ModelFilesGetter.call(options).each do |file|
-            file = File.join(file)
+
+          model_files_to_consider = ModelFilesGetter.call(options)
+
+          model_files_to_consider.each do |path, filename|
+            deannotated_klass = false
+            file = File.join(path, filename)
+
             begin
               klass = ModelClassGetter.call(file, options)
               if klass < ActiveRecord::Base && !klass.abstract_class?
                 model_name = klass.name.underscore
                 table_name = klass.table_name
-                model_file_name = file
-                deannotated_klass = true if FileAnnotationRemover.call(model_file_name, options)
 
-                patterns = PatternGetter.call(options)
+                if FileAnnotationRemover.call(file, options)
+                  deannotated_klass = true
+                end
+
+                related_files = RelatedFilesListBuilder.new(file, model_name, table_name, options).build
 
-                patterns
-                  .map { |f| FileNameResolver.call(f, model_name, table_name) }
-                  .each do |f|
+                related_files.each do |f, _position_key|
                   if File.exist?(f)
                     FileAnnotationRemover.call(f, options)
-                    deannotated_klass = true
                   end
                 end
               end
-              deannotated << klass if deannotated_klass
+
+              if deannotated_klass
+                deannotated << klass
+              end
             rescue StandardError => e
               $stderr.puts "Unable to deannotate #{File.join(file)}: #{e.message}"
               $stderr.puts "\t" + e.backtrace.join("\n\t") if options[:trace]
             end
           end
+
           puts "Removed annotations from: #{deannotated.join(', ')}"
         end
       end

data/lib/annotate_rb/model_annotator/column_annotation_builder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class ColumnAnnotationBuilder
+      BARE_TYPE_ALLOWANCE = 16
+      MD_TYPE_ALLOWANCE = 18
+
+      def initialize(column, model, max_size, options)
+        @column = column
+        @model = model
+        @max_size = max_size
+        @options = options
+      end
+
+      def build
+        result = ''
+
+        is_primary_key = is_column_primary_key?(@model, @column.name)
+
+        table_indices = @model.retrieve_indexes_from_table
+        column_indices = table_indices.select { |ind| ind.columns.include?(@column.name) }
+
+        column_attributes = ColumnAttributesBuilder.new(@column, @options, is_primary_key, column_indices).build
+        formatted_column_type = ColumnTypeBuilder.new(@column, @options).build
+
+        col_name = if @model.with_comments? && @column.comment
+                     "#{@column.name}(#{@column.comment.gsub(/\n/, '\\n')})"
+                   else
+                     @column.name
+                   end
+
+        if @options[:format_rdoc]
+          result += format("# %-#{@max_size}.#{@max_size}s<tt>%s</tt>",
+                           "*#{col_name}*::",
+                           column_attributes.unshift(formatted_column_type).join(', ')).rstrip + "\n"
+        elsif @options[:format_yard]
+          result += sprintf("# @!attribute #{col_name}") + "\n"
+
+          if @column.respond_to?(:array) && @column.array
+            ruby_class = "Array<#{Helper.map_col_type_to_ruby_classes(formatted_column_type)}>"
+          else
+            ruby_class = Helper.map_col_type_to_ruby_classes(formatted_column_type)
+          end
+
+          result += sprintf("#   @return [#{ruby_class}]") + "\n"
+        elsif @options[:format_markdown]
+          name_remainder = @max_size - col_name.length - Helper.non_ascii_length(col_name)
+          type_remainder = (MD_TYPE_ALLOWANCE - 2) - formatted_column_type.length
+          result += format("# **`%s`**%#{name_remainder}s | `%s`%#{type_remainder}s | `%s`",
+                           col_name,
+                           ' ',
+                           formatted_column_type,
+                           ' ',
+                           column_attributes.join(', ').rstrip).gsub('``', '  ').rstrip + "\n"
+        else
+          result += format_default(col_name, @max_size, formatted_column_type, column_attributes)
+        end
+
+        result
+      end
+
+      private
+
+      def format_default(col_name, max_size, col_type, attrs)
+        format('#  %s:%s %s',
+               Helper.mb_chars_ljust(col_name, max_size),
+               Helper.mb_chars_ljust(col_type, BARE_TYPE_ALLOWANCE),
+               attrs.join(', ')).rstrip + "\n"
+      end
+
+      # TODO: Simplify this conditional
+      def is_column_primary_key?(model, column_name)
+        if model.primary_key
+          if model.primary_key.is_a?(Array)
+            # If the model has multiple primary keys, check if this column is one of them
+            if model.primary_key.collect(&:to_sym).include?(column_name.to_sym)
+              return true
+            end
+          else
+            # If model has 1 primary key, check if this column is it
+            if column_name.to_sym == model.primary_key.to_sym
+              return true
+            end
+          end
+        end
+
+        false
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/column_attributes_builder.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class ColumnAttributesBuilder
+      # Don't show default value for these column types
+      NO_DEFAULT_COL_TYPES = %w[json jsonb hstore].freeze
+
+      def initialize(column, options, is_primary_key, column_indices)
+        @column = ColumnWrapper.new(column)
+        @options = options
+        @is_primary_key = is_primary_key
+        @column_indices = column_indices
+      end
+
+      # Get the list of attributes that should be included in the annotation for
+      # a given column.
+      def build
+        column_type = @column.column_type_string
+        attrs = []
+
+        unless @column.default.nil? || hide_default?
+          schema_default = "default(#{@column.default_string})"
+
+          attrs << schema_default
+        end
+
+        if @column.unsigned?
+          attrs << 'unsigned'
+        end
+
+        if !@column.null
+          attrs << 'not null'
+        end
+
+        if @is_primary_key
+          attrs << 'primary key'
+        end
+
+        is_special_type = %w[spatial geometry geography].include?(column_type)
+        is_decimal_type = column_type == 'decimal'
+
+        if !is_decimal_type && !is_special_type
+          if @column.limit && !@options[:format_yard]
+            if @column.limit.is_a?(Array)
+              attrs << "(#{@column.limit.join(', ')})"
+            end
+          end
+        end
+
+        # Check out if we got an array column
+        if @column.array?
+          attrs << 'is an Array'
+        end
+
+        # Check out if we got a geometric column
+        # and print the type and SRID
+        if @column.geometry_type?
+          attrs << "#{@column.geometry_type}, #{@column.srid}"
+        elsif @column.geometric_type? && @column.geometric_type.present?
+          attrs << "#{@column.geometric_type.to_s.downcase}, #{@column.srid}"
+        end
+
+        # Check if the column has indices and print "indexed" if true
+        # If the index includes another column, print it too.
+        if @options[:simple_indexes]
+          # Note: there used to be a klass.table_exists? call here, but removed it as it seemed unnecessary.
+
+          sorted_column_indices&.each do |index|
+            indexed_columns = index.columns.reject { |i| i == @column.name }
+
+            if indexed_columns.empty?
+              attrs << 'indexed'
+            else
+              attrs << "indexed => [#{indexed_columns.join(', ')}]"
+            end
+          end
+        end
+
+        attrs
+      end
+
+      def sorted_column_indices
+        # Not sure why there were & safe accessors here, but keeping in for time being.
+        sorted_indices = @column_indices&.sort_by(&:name)
+
+        _sorted_indices = sorted_indices.reject { |ind| ind.columns.is_a?(String) }
+      end
+
+      def hide_default?
+        excludes =
+          if @options[:hide_default_column_types].blank?
+            NO_DEFAULT_COL_TYPES
+          else
+            @options[:hide_default_column_types].split(',')
+          end
+
+        excludes.include?(@column.column_type_string)
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/column_type_builder.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class ColumnTypeBuilder
+      # Don't show limit (#) on these column types
+      # Example: show "integer" instead of "integer(4)"
+      NO_LIMIT_COL_TYPES = %w[integer bigint boolean].freeze
+
+      def initialize(column, options)
+        @column = ColumnWrapper.new(column)
+        @options = options
+      end
+
+      # Returns the formatted column type as a string.
+      def build
+        column_type = @column.column_type_string
+
+        formatted_column_type = column_type
+
+        is_special_type = %w[spatial geometry geography].include?(column_type)
+        is_decimal_type = column_type == 'decimal'
+
+        if is_decimal_type
+          formatted_column_type = "decimal(#{@column.precision}, #{@column.scale})"
+        elsif is_special_type
+          # Do nothing. Kept as a code fragment in case we need to do something here.
+        else
+          if @column.limit && !@options[:format_yard]
+            if !@column.limit.is_a?(Array) && !hide_limit?
+              formatted_column_type = column_type + "(#{@column.limit})"
+            end
+          end
+        end
+
+        formatted_column_type
+      end
+
+      def hide_limit?
+        excludes =
+          if @options[:hide_limit_column_types].blank?
+            NO_LIMIT_COL_TYPES
+          else
+            @options[:hide_limit_column_types].split(',')
+          end
+
+        excludes.include?(@column.column_type_string)
+      end
+    end
+  end
+end