rails-annotate-solargraph 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7bb66133bae3d570210fe56d3b0b707666551af81bbc2923a8cf7d589ec0ad8
-  data.tar.gz: 4591722333e2d9b770ba3b33887a85ed37e846d7a8f3a03913cba4ab4627f828
+  metadata.gz: 744b5deaf3bfdd5fdf4b81b54abd8f4672336402bce178af67b04ff704b6ceab
+  data.tar.gz: 062d49842f237ddb38202975c0c88733fb3a825ebcb4c7cbd7641b45b58ee993
 SHA512:
-  metadata.gz: 30d537b5e78042ba0dc990af3030b1ff1fb85232c3f998da008d1eaba6c83b2ab543c2c33adbe87ce181f4f6f9954ac500e077b4134dac9801498455e83e3b0e
-  data.tar.gz: a36382741d8e9964835a8818a3091d26c4d18c3e798ec0e77636e47e1c7cd172f0f17086bc4869022b1552bfac91cded203def21723e9a99f3d687ab8fcba903
+  metadata.gz: 35eb981e6a0b52331164d80fd7238aadae0403cd9f4d93c7dc9a6c00e31714f6b731c23e961542ee5eac64a48c2820de926fcacaea1e6b8ff9b34c501781c05b
+  data.tar.gz: 6d0f472969a50ed833398216789d0000b8c288685946ab90621f48edca85f57034350df39a5006ae5ddb6b4a30623658c529584e6eca504b0202ff6b633b3379

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.2.0] - 2022-04-16
+
+- Associations get fully documented
+
+## [0.1.1] - 2022-04-15
+
+- Minor bug fix after the initial release
+
 ## [0.1.0] - 2022-04-15
 
 - Initial release
+- Automatic generation of annotations after migrations
+- Manual rake tasks `annotate:solargraph:generate`, `annotate:solargraph:remove`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rails-annotate-solargraph (0.1.1)
+    rails-annotate-solargraph (0.2.0)
       rails (>= 5.0, < 8.0)
 
 GEM

data/lib/generators/annotate/solargraph/templates/rails_annotate_solargraph.rake

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
+include ::Rails::Annotate::Solargraph::TerminalColors
+
 if ::Rails.env.development?
   namespace :annotate do
     namespace :solargraph do
       desc "Add YARD comments documenting the models' schemas"
       task generate: :environment do
-        system 'rails runner "p ::Rails::Annotate::Solargraph.generate"'
+        system! 'bundle exec bin/rails runner "::Rails::Annotate::Solargraph.generate"'
       end
 
       desc "Remove YARD comments documenting the models' schemas"
       task remove: :environment do
-        system 'rails runner "p ::Rails::Annotate::Solargraph.remove"'
+        system! 'bundle exec bin/rails runner "::Rails::Annotate::Solargraph.remove"'
       end
     end
 
@@ -23,4 +25,8 @@ if ::Rails.env.development?
       end
     end
   end
+
+  def system!(val)
+    system(val) || abort(error_string("Command `#{val}` failed"))
+  end
 end

data/lib/rails/annotate/solargraph/model.rb

@@ -4,9 +4,15 @@ module Rails
   module Annotate
     module Solargraph
       class Model
+        using TerminalColors::Refinement
+
+        # @return [String]
         ANNOTATION_START = "\n# %%<RailsAnnotateSolargraph:Start>%%"
+        # @return [String]
         ANNOTATION_END = "%%<RailsAnnotateSolargraph:End>%%\n\n"
+        # @return [Regexp]
         ANNOTATION_REGEXP = /#{ANNOTATION_START}.*#{ANNOTATION_END}/m.freeze
+        # @return [Regexp]
         MAGIC_COMMENT_REGEXP = /(^#\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
@@ -51,7 +57,7 @@ module Rails
         # @param :write [Boolean]
         # @return [String] New file content.
         def annotate(write: true)
-          file_content = remove_annotation write: false
+          old_content, file_content = remove_annotation write: false
 
           if CONFIG.annotation_position == :top
             magic_comments = file_content.scan(MAGIC_COMMENT_REGEXP).flatten.compact.join
@@ -63,35 +69,43 @@ module Rails
           end
 
           return new_file_content unless write
-          return new_file_content if file_content == new_file_content
+          # debugger
+          return new_file_content if old_content == new_file_content
 
-          ::File.write @file_name, new_file_content
+          write_file @file_name, new_file_content
           new_file_content
         end
 
         # @param :write [Boolean]
-        # @return [String] New file content.
+        # @return [Array<String>] Old file content followed by new content.
         def remove_annotation(write: true)
           file_content = ::File.read(@file_name)
           new_file_content = file_content.sub(ANNOTATION_REGEXP, '')
-          return new_file_content unless write
-          return new_file_content if file_content == new_file_content
+          result = [file_content, new_file_content]
+          return result unless write
+          return result if file_content == new_file_content
 
-          ::File.write @file_name, new_file_content
-          new_file_content
+          write_file @file_name, new_file_content
+          result
         end
 
         # @return [String]
         def annotation
-          result = ::String.new
-          result << <<~DOC
+          doc_string = ::String.new
+          doc_string << <<~DOC
             #{ANNOTATION_START}
             # @!parse
             #   class #{@klass} < #{@klass.superclass}
           DOC
 
+          @klass.reflections.sort.each do |attr_name, reflection|
+            next document_polymorphic_relation(doc_string, attr_name, reflection) if reflection.polymorphic?
+
+            document_relation(doc_string, attr_name, reflection)
+          end
+
           @klass.attribute_types.each do |name, attr_type|
-            result << <<~DOC
+            doc_string << <<~DOC
               #     # Database column `#{@klass.table_name}.#{name}`, type: `#{attr_type.type}`.
               #     # @param val [#{yard_type attr_type}, nil]
               #     def #{name}=(val); end
@@ -101,7 +115,7 @@ module Rails
             DOC
           end
 
-          result << <<~DOC.chomp
+          doc_string << <<~DOC.chomp
             #   end
             # #{ANNOTATION_END}
           DOC
@@ -109,6 +123,73 @@ module Rails
 
         private
 
+        # @param file_name [String]
+        # @return [String]
+        def relative_file_name(file_name)
+          file_name.delete_prefix("#{::Rails.root}/")
+        end
+
+        # @param file_name [String]
+        # @param content [String]
+        # @return [void]
+        def write_file(file_name, content)
+          ::File.write(file_name, content)
+          puts "modify".rjust(12).with_styles(:bold, :green) + "  #{relative_file_name(file_name)}"
+        end
+
+        # @return [String]
+        def klass_relation_name
+          @klass.table_name[..-2]
+        end
+
+        # @param doc_string [String]
+        # @param attr_name [String]
+        # @param reflection [ActiveRecord::Reflection::AbstractReflection]
+        # @return [void]
+        def document_relation(doc_string, attr_name, reflection)
+          db_description = \
+            case reflection
+            when ::ActiveRecord::Reflection::BelongsToReflection
+              type_docstring = reflection.klass
+              "`belongs_to` relation with `#{reflection.klass}`. Database column `#{@klass.table_name}.#{reflection.foreign_key}`."
+            when ::ActiveRecord::Reflection::HasOneReflection
+              type_docstring = reflection.klass
+              "`has_one` relation with `#{reflection.klass}`. Database column `#{reflection.klass.table_name}.#{reflection.foreign_key}`."
+            when ::ActiveRecord::Reflection::HasManyReflection
+              type_docstring = "Array<#{reflection.klass}>"
+              "`has_many` relation with `#{reflection.klass}`. Database column `#{reflection.klass.table_name}.#{reflection.foreign_key}`."
+            end
+
+          doc_string << <<~DOC
+            #     # #{db_description}
+            #     # @param val [#{type_docstring}, nil]
+            #     def #{attr_name}=(val); end
+            #     # #{db_description}
+            #     # @return [#{type_docstring}, nil]
+            #     def #{attr_name}; end
+          DOC
+        end
+
+        # @param doc_string [String]
+        # @param attr_name [String]
+        # @param reflection [ActiveRecord::Reflection::AbstractReflection]
+        # @return [void]
+        def document_polymorphic_relation(doc_string, attr_name, reflection)
+          classes = Solargraph.model_classes.select do |model_class|
+            model_class.reflections[klass_relation_name]&.options&.[](:as)&.to_sym == attr_name.to_sym
+          end
+
+          classes_string = classes.join(', ')
+          doc_string << <<~DOC
+            #     # Polymorphic relation. Database columns `#{@klass.table_name}.#{attr_name}_id` and `#{@klass.table_name}.#{attr_name}_type`.
+            #     # @param val [#{classes_string}, nil]
+            #     def #{attr_name}=(val); end
+            #     # Polymorphic relation. Database columns `#{@klass.table_name}.#{attr_name}_id` and `#{@klass.table_name}.#{attr_name}_type`.
+            #     # @return [#{classes_string}, nil]
+            #     def #{attr_name}; end
+          DOC
+        end
+
         # @param attr_type [ActiveModel::Type::Value]
         # @return [String]
         def yard_type(attr_type)

data/lib/rails/annotate/solargraph/terminal_colors.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Rails
+  module Annotate
+    module Solargraph
+      module TerminalColors
+        extend self
+
+        # @return [Hash{Symbol => String}]
+        MAP = {
+          blue: (BLUE = "\033[94m"),
+          cyan: (CYAN = "\033[96m"),
+          green: (GREEN = "\033[92m"),
+          yellow: (YELLOW = "\033[93m"),
+          red: (RED = "\033[91m"),
+          terminate: (TERMINATE = "\033[0m"),
+          bold: (BOLD = "\033[1m"),
+          italic: (ITALIC = "\033[3m"),
+          underline: (UNDERLINE = "\033[4m")
+        }.freeze
+
+        class << self
+          # Style a string with an ASCII escape code
+          #
+          # @param string [String]
+          # @param style [Symbol]
+          # @return [String]
+          def with_style(string, style)
+            "#{MAP[style]}#{string}#{TERMINATE}"
+          end
+
+          # Style a string with multiple ASCII escape codes
+          #
+          # @param string [String]
+          # @param styles [Array<Symbol>]
+          # @return [String]
+          def with_styles(string, *styles)
+            result = ::String.new
+            styles.each do |style|
+              result << MAP[style]
+            end
+
+            result << "#{string}#{TERMINATE}"
+          end
+        end
+
+        def title_string(string)
+          TerminalColors.with_styles "== #{string} ==", :cyan, :underline, :italic
+        end
+
+        def error_string(string)
+          TerminalColors.with_styles "!! #{string} !!", :bold, :red
+        end
+
+        def title(string)
+          puts "\n", title_string(string)
+        end
+
+        def error(string)
+          puts "\n", error_string(string)
+        end
+
+        module Refinement
+          refine ::String do
+            # @param styles [Array<Symbol]>
+            # @return [self] Colored string
+            def with_styles(*styles)
+              ::Rails::Annotate::Solargraph::TerminalColors.with_styles(self, *styles)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/annotate/solargraph/version.rb

@@ -3,7 +3,7 @@
 module Rails
   module Annotate
     module Solargraph
-      VERSION = '0.1.1'
+      VERSION = '0.2.0'
     end
   end
 end

data/lib/rails/annotate/solargraph.rb

@@ -4,6 +4,7 @@ require 'set'
 
 require_relative "solargraph/version"
 require_relative "solargraph/configuration"
+require_relative "solargraph/terminal_colors"
 require_relative "solargraph/model"
 
 module Rails
@@ -16,15 +17,19 @@ module Rails
       RAKEFILE_NAME = 'rails_annotate_solargraph.rake'
       # @return [Configuration]
       CONFIG = Configuration.new
+      # @return [Set<Symbol>]
+      VALID_MODIFICATION_METHODS = ::Set[:annotate, :remove_annotation].freeze
 
       class << self
         # @return [Array<String>] Array of changed files.
         def generate
+          title 'Generating model schema annotations'
           modify_models :annotate
         end
 
         # @return [Array<String>] Array of changed files.
         def remove
+          title 'Removing model schema annotations'
           modify_models :remove_annotation
         end
 
@@ -35,10 +40,15 @@ module Rails
 
         alias call generate
 
-        VALID_MODIFICATION_METHODS = ::Set[:annotate, :remove_annotation]
+        # @return [Array<ActiveRecord::Base>]
+        def model_classes
+          @model_classes ||= (::ApplicationRecord rescue ::ActiveRecord::Base).subclasses.sort_by(&:name)
+        end
 
         private
 
+        include TerminalColors
+
         # @param method [Symbol] Name of the method that will be called on every loaded Model
         # @return [Array<String>] Array of changed files.
         def modify_models(method)
@@ -49,7 +59,7 @@ module Rails
           model_files = ::Dir[::File.join(::Rails.root, MODEL_DIR, '**/*.rb')].map { |file| file.sub("#{::Rails.root}/", '') }.to_set
 
           ::Rails.application.eager_load!
-          (::ApplicationRecord rescue ::ActiveRecord::Base).subclasses.each do |subclass|
+          model_classes.each do |subclass|
             subclass_file = ::File.join MODEL_DIR, "#{subclass.to_s.underscore}.rb"
             next unless model_files.include? subclass_file
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-annotate-solargraph
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Mateusz Drewniak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-04-15 00:00:00.000000000 Z
+date: 2022-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -57,6 +57,7 @@ files:
 - lib/rails/annotate/solargraph.rb
 - lib/rails/annotate/solargraph/configuration.rb
 - lib/rails/annotate/solargraph/model.rb
+- lib/rails/annotate/solargraph/terminal_colors.rb
 - lib/rails/annotate/solargraph/version.rb
 - rails-annotate-solargraph.gemspec
 - sig/rails/annotate/solargraph.rbs