rails-annotate-solargraph 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d62415c07dd7235a4151593d2def72a55a7f8b7f7785f71eb66fe6996ce657d
-  data.tar.gz: a4737b994cb8ece0516da3d2e57ba66e05a5243cfc29ad1149f99bb03e1f8d1b
+  metadata.gz: 80d2fcb8fc2090d6a1eabc8f510b3b9fec1608da1870c7d88b301ce64907920a
+  data.tar.gz: 9553090d359f8f829e955349cac6c527c43335433e38d91152862780cce3ab63
 SHA512:
-  metadata.gz: b67bd482cf97936d6b55a9c28b5845a45a53650683cc05a89823427573aee2d66ac9500147b53c8b18ab74c6883f3f3306db864341aa03344ca5c376a6173892
-  data.tar.gz: 96d4d8aff31ee3a530635959539483572c268164c0214701e7b286cbcde37069419752ea3fd5b0bf466d5480dcdb4637f97952f764b932ea2824b8a14ec025c5
+  metadata.gz: 8b2415d929d939454a4f65277d85baa03935219226c6ad5b35c35264cd2de94bb1b1d55a55a55ee8cc737523210e3653c648bea50798dd53b580767fbb6a2eec
+  data.tar.gz: 9436e870a6cbc28e636151b76717cde5bf4186f44bc8af4293ada785f1c50e039895fcf5cb38dd27868c5e88027df9f52be8ee070591e0635de30fdba7437aef

data/.vscode/settings.json

@@ -1,6 +1,7 @@
 {
   "cSpell.words": [
     "activerecord",
+    "klass",
     "rakefile",
     "solargraph",
     "yieldparam"

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.4.0] - 2022-04-17
+
+- Annotations get saved to a schema file by default `app/models/annotate_solargraph_schema.rb`
+
+## [0.3.0] - 2022-04-17
+
+- `has_many :through` and `has_one :through` relations get documented
+
+## [0.2.3] - 2022-04-16
+
+- A nicer fix for the previous problem
+
 ## [0.2.2] - 2022-04-16
 
 - Inexistent class loading error has been resolved
@@ -11,6 +23,7 @@
 ## [0.2.0] - 2022-04-16
 
 - Associations get fully documented
+- `has_many`, `has_one` and `belongs_to` relations get documented
 
 ## [0.1.1] - 2022-04-15
 
@@ -20,4 +33,5 @@
 
 - Initial release
 - Automatic generation of annotations after migrations
+- Database fields get documented
 - Manual rake tasks `annotate:solargraph:generate`, `annotate:solargraph:remove`

data/Gemfile.lock

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

data/README.md

@@ -63,11 +63,31 @@ You can change the gem's default configuration like so:
 ```ruby
 # config/initializers/rails_annotate_solargraph.rb
 
-Rails::Annotate::Solargraph.configure do |conf|
-    conf.annotation_position = :top # `:bottom` by default
+if ::Rails.env.development?
+    ::Rails::Annotate::Solargraph.configure do |conf|
+        conf.annotation_position = :top # `:schema_file` by default
+    end
 end
 ```
 
+#### annotation_position
+
+There are a few values for this option:
+
+- `:schema_file` -- default value, annotations get saved to a special file `app/models/annotate_solargraph_schema.rb`
+- `:bottom` -- annotations are appended to the model files
+- `:top` -- annotations are prepended to the model files
+
+### Update
+
+To update this gem you should generate the rakefiles once again. Overwrite them.
+
+```sh
+$ rails g annotate:solargraph:install
+$ rake annotate:solargraph:remove
+$ rake annotate:solargraph:generate
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

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

@@ -9,10 +9,10 @@ module Rails
         # @return [Symbol]
         attr_reader :annotation_position
 
-        ANNOTATION_POSITIONS = ::Set[:bottom, :top].freeze
+        ANNOTATION_POSITIONS = ::Set[:bottom, :top, :schema_file].freeze
 
         def initialize
-          @annotation_position = :bottom
+          @annotation_position = :schema_file
         end
 
         # @param val [Symbol]
@@ -22,6 +22,10 @@ module Rails
 
           @annotation_position = val
         end
+
+        def schema_file?
+          @annotation_position == :schema_file
+        end
       end
     end
   end

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

@@ -1,32 +1,16 @@
 # frozen_string_literal: true
 
+require 'fileutils'
+
 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 << (FAKE_MODEL_CLASS = Object.new)
-          def to_s
-            ::Object.to_s
-          end
-
-          alias name to_s
-
-          def table_name
-            '<unknown>'
-          end
-        end
-
         class << self
           # @param type [Symbol, String, nil]
           # @return [String]
@@ -52,6 +36,26 @@ module Rails
               ::Object.to_s
             end
           end
+
+          # @param klass [Class]
+          # @return [String]
+          def annotation_start(klass = nil)
+            table_name = klass && CONFIG.schema_file? ? ":#{klass.table_name}" : ''
+            "\n# %%<RailsAnnotateSolargraph:Start#{table_name}>%%"
+          end
+
+          # @param klass [Class]
+          # @return [String]
+          def annotation_end(klass = nil)
+            table_name = klass && CONFIG.schema_file? ? ":#{klass.table_name}" : ''
+            "%%<RailsAnnotateSolargraph:End#{table_name}>%%\n\n"
+          end
+
+          # @param klass [Class]
+          # @return [Regexp]
+          def annotation_regexp(klass = nil)
+            /#{annotation_start(klass)}.*#{annotation_end(klass)}/m
+          end
         end
 
         # @return [String]
@@ -63,7 +67,23 @@ module Rails
         # @param klass [Class]
         def initialize(klass)
           @klass = klass
-          @file_name = ::File.join(::Rails.root, MODEL_DIR, "#{klass.to_s.underscore}.rb")
+          base_file_name = CONFIG.schema_file? ? SCHEMA_FILE_NAME : "#{klass.to_s.underscore}.rb"
+          @file_name = ::File.join(::Rails.root, MODEL_DIR, base_file_name)
+        end
+
+        # @return [String]
+        def annotation_start
+          self.class.annotation_start(@klass)
+        end
+
+        # @return [String]
+        def annotation_end
+          self.class.annotation_end(@klass)
+        end
+
+        # @return [Regexp]
+        def annotation_regexp
+          self.class.annotation_regexp(@klass)
         end
 
         # @param :write [Boolean]
@@ -91,8 +111,10 @@ module Rails
         # @param :write [Boolean]
         # @return [Array<String>] Old file content followed by new content.
         def remove_annotation(write: true)
+          return ['', ''] unless ::File.exist?(@file_name)
+
           file_content = ::File.read(@file_name)
-          new_file_content = file_content.sub(ANNOTATION_REGEXP, '')
+          new_file_content = file_content.sub(annotation_regexp, '')
           result = [file_content, new_file_content]
           return result unless write
           return result if file_content == new_file_content
@@ -105,7 +127,7 @@ module Rails
         def annotation
           doc_string = ::String.new
           doc_string << <<~DOC
-            #{ANNOTATION_START}
+            #{annotation_start}
             # @!parse
             #   class #{@klass} < #{@klass.superclass}
           DOC
@@ -129,7 +151,7 @@ module Rails
 
           doc_string << <<~DOC.chomp
             #   end
-            # #{ANNOTATION_END}
+            # #{annotation_end}
           DOC
         end
 
@@ -145,6 +167,7 @@ module Rails
         # @param content [String]
         # @return [void]
         def write_file(file_name, content)
+          ::FileUtils.touch(file_name) unless ::File.exists?(file_name)
           ::File.write(file_name, content)
           puts "modify".rjust(12).with_styles(:bold, :green) + "  #{relative_file_name(file_name)}"
         end
@@ -154,35 +177,57 @@ module Rails
           @klass.table_name[..-2]
         end
 
+        # @param reflection [ActiveRecord::Reflection::AbstractReflection]
+        # @return [Class]
+        def reflection_class(reflection)
+          reflection.klass
+        rescue ::NameError
+          Object
+        end
+
+        # @param reflection [ActiveRecord::Reflection::AbstractReflection]
+        # @return [String]
+        def reflection_foreign_key(reflection)
+          reflection.try(:foreign_key) || '<unknown>'
+        end
+
+        # @param klass [Class]
+        # @return [String]
+        def class_table_name(klass)
+          klass.try(:table_name) || '<unknown>'
+        end
+
         # @param doc_string [String]
         # @param attr_name [String]
         # @param reflection [ActiveRecord::Reflection::AbstractReflection]
         # @return [void]
         def document_relation(doc_string, attr_name, reflection)
-          reflection_class = begin
-            reflection.klass
-          rescue ::NameError
-            FAKE_MODEL_CLASS
-          end
-
-          db_description = \
+          reflection_klass = reflection_class(reflection)
+          type_docstring, db_description = \
             case reflection
             when ::ActiveRecord::Reflection::BelongsToReflection
-              type_docstring = reflection_class
-              "`belongs_to` relation with `#{reflection_class}`. Database column `#{@klass.table_name}.#{reflection.foreign_key}`."
+              belongs_to_description(reflection_klass,
+                                     class_table_name(@klass),
+                                     reflection_foreign_key(reflection))
             when ::ActiveRecord::Reflection::HasOneReflection
-              type_docstring = reflection_class
-              "`has_one` relation with `#{reflection_class}`. Database column `#{reflection_class.table_name}.#{reflection.foreign_key}`."
+              has_one_description(reflection_klass,
+                                  class_table_name(reflection_klass),
+                                  reflection_foreign_key(reflection))
             when ::ActiveRecord::Reflection::HasManyReflection
-              type_docstring = "Array<#{reflection_class}>"
-              "`has_many` relation with `#{reflection_class}`. Database column `#{reflection_class.table_name}.#{reflection.foreign_key}`."
+              has_many_description(reflection_klass,
+                                   class_table_name(reflection_klass),
+                                   reflection_foreign_key(reflection))
+            when ::ActiveRecord::Reflection::ThroughReflection
+              through_description(reflection)
+            else
+              [::Object.to_s, '']
             end
 
           doc_string << <<~DOC
-            #     # #{db_description}
+            #     ##{db_description}
             #     # @param val [#{type_docstring}, nil]
             #     def #{attr_name}=(val); end
-            #     # #{db_description}
+            #     ##{db_description}
             #     # @return [#{type_docstring}, nil]
             #     def #{attr_name}; end
           DOC
@@ -197,7 +242,7 @@ module Rails
             model_class.reflections[klass_relation_name]&.options&.[](:as)&.to_sym == attr_name.to_sym
           end
 
-          classes_string = classes.join(', ')
+          classes_string = classes.empty? ? ::Object.to_s : 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]
@@ -208,6 +253,91 @@ module Rails
           DOC
         end
 
+        # @param reflection [ActiveRecord::Reflection::AbstractReflection]
+        # @return [Array<String>]
+        def through_description(reflection)
+          through_klass = reflection_class(reflection.through_reflection)
+
+          case (reflection.__send__(:delegate_reflection) rescue nil)
+          when ::ActiveRecord::Reflection::HasOneReflection
+            has_one_description(reflection_class(reflection.source_reflection),
+                                class_table_name(through_klass),
+                                reflection_foreign_key(reflection.source_reflection),
+                                through: through_klass)
+          when ::ActiveRecord::Reflection::HasManyReflection
+            has_many_description(reflection_class(reflection.source_reflection),
+                                 class_table_name(through_klass),
+                                 reflection_foreign_key(reflection.source_reflection),
+                                 through: through_klass)
+          else
+            [::Object.to_s, '']
+          end
+        end
+
+        # @param through [Class, nil]
+        # @return [String]
+        def through_sentence(through = nil)
+          return '' unless through
+
+          " through `#{through}`"
+        end
+
+        # @param table_name [String]
+        # @param foreign_key [String]
+        # @param through [Class, nil]
+        # @return [String]
+        def column_description(table_name, foreign_key, through = nil)
+          return '' if through
+
+          " Database column `#{table_name}.#{foreign_key}`."
+        end
+
+        # @param relation [Symbol, String]
+        # @param klass [Class]
+        # @param table_name [String]
+        # @param foreign_key [String]
+        # @param through [Class, nil]
+        # @return [String]
+        def relation_description(relation, klass, table_name, foreign_key, through = nil)
+          " `#{relation}` relation with `#{klass}`#{through_sentence(through)}.#{column_description(table_name, foreign_key, through)}"
+        end
+
+
+        # @param klass [Class]
+        # @param table_name [String]
+        # @param foreign_key [String]
+        # @param :through [Class, nil]
+        # @return [Array<String>] Type docstring followed by the description of the method.
+        def has_many_description(klass, table_name, foreign_key, through: nil)
+          type_docstring = "Array<#{klass}>"
+          desc = relation_description(:has_many, klass, table_name, foreign_key, through)
+
+          [type_docstring, desc]
+        end
+
+        # @param klass [Class]
+        # @param table_name [String]
+        # @param foreign_key [String]
+        # @param :through [Class, nil]
+        # @return [Array<String>] Type docstring followed by the description of the method.
+        def has_one_description(klass, table_name, foreign_key, through: nil)
+          type_docstring = klass
+          desc = relation_description(:has_one, klass, table_name, foreign_key, through)
+
+          [type_docstring, desc]
+        end
+
+        # @param klass [Class]
+        # @param table_name [String]
+        # @param foreign_key [String]
+        # @return [Array<String>] Type docstring followed by the description of the method.
+        def belongs_to_description(klass, table_name, foreign_key)
+          type_docstring = klass
+          desc = relation_description(:belongs_to, klass, table_name, foreign_key)
+
+          [type_docstring, desc]
+        end
+
         # @param attr_type [ActiveModel::Type::Value]
         # @return [String]
         def yard_type(attr_type)

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

@@ -3,7 +3,7 @@
 module Rails
   module Annotate
     module Solargraph
-      VERSION = '0.2.2'
+      VERSION = '0.4.0'
     end
   end
 end

data/lib/rails/annotate/solargraph.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'set'
+require 'fileutils'
 
 require_relative "solargraph/version"
 require_relative "solargraph/configuration"
@@ -19,11 +20,16 @@ module Rails
       CONFIG = Configuration.new
       # @return [Set<Symbol>]
       VALID_MODIFICATION_METHODS = ::Set[:annotate, :remove_annotation].freeze
+      # @return [String]
+      SCHEMA_CLASS_NAME = 'AnnotateSolargraphSchema'
+      # @return [String]
+      SCHEMA_FILE_NAME = "annotate_solargraph_schema.rb"
 
       class << self
         # @return [Array<String>] Array of changed files.
         def generate
           title 'Generating model schema annotations'
+          create_schema_file
           modify_models :annotate
         end
 
@@ -49,6 +55,16 @@ module Rails
 
         include TerminalColors
 
+        def create_schema_file
+          schema_file = ::File.join(::Rails.root, MODEL_DIR, SCHEMA_FILE_NAME)
+          return unless CONFIG.schema_file? && !::File.exist?(schema_file)
+
+          ::FileUtils.touch(schema_file)
+          ::File.write schema_file, <<~SCHEMA
+            module AnnotateSolargraphSchema; end
+          SCHEMA
+        end
+
         # @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)

data/rails-annotate-solargraph.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://gitlab.com/mateuszdrewniak/rails-annotate-solargraph"
-  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+  spec.metadata["changelog_uri"] = "https://gitlab.com/mateuszdrewniak/rails-annotate-solargraph/-/raw/main/CHANGELOG.md"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-annotate-solargraph
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Mateusz Drewniak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-04-16 00:00:00.000000000 Z
+date: 2022-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -67,6 +67,7 @@ licenses:
 metadata:
   homepage_uri: https://gitlab.com/mateuszdrewniak/rails-annotate-solargraph
   source_code_uri: https://gitlab.com/mateuszdrewniak/rails-annotate-solargraph
+  changelog_uri: https://gitlab.com/mateuszdrewniak/rails-annotate-solargraph/-/raw/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: