rails-annotate-solargraph 0.4.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80d2fcb8fc2090d6a1eabc8f510b3b9fec1608da1870c7d88b301ce64907920a
-  data.tar.gz: 9553090d359f8f829e955349cac6c527c43335433e38d91152862780cce3ab63
+  metadata.gz: ac8d7c78804560db17c10943c462e838059d5f74d6d5d2664083c6da0f26c43a
+  data.tar.gz: b9a0d329cb657bdb74220b75ec14a53785d75f2e6847c7bc41e884103edb21df
 SHA512:
-  metadata.gz: 8b2415d929d939454a4f65277d85baa03935219226c6ad5b35c35264cd2de94bb1b1d55a55a55ee8cc737523210e3653c648bea50798dd53b580767fbb6a2eec
-  data.tar.gz: 9436e870a6cbc28e636151b76717cde5bf4186f44bc8af4293ada785f1c50e039895fcf5cb38dd27868c5e88027df9f52be8ee070591e0635de30fdba7437aef
+  metadata.gz: 39567ae796da52823201081813575f0859aefad622a5c43522b0b82f0864f4f87a8e3cccc65a83d9631c9a6f4c9febae0968b2e51980d679d7f0736e6c55c552
+  data.tar.gz: a8d6a79aa396d9110bc157703678d91f8b0e0f664f4175f296a47e07429727dbc3eb7d3e6025facaaff3b3abea94f151abeaece7e07f2160ba4eb1d48cf23c88

data/.vscode/settings.json

@@ -1,6 +1,10 @@
 {
   "cSpell.words": [
     "activerecord",
+    "citext",
+    "datetime",
+    "gsub",
+    "inet",
     "klass",
     "rakefile",
     "solargraph",

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.5.2] - 2022-04-20
+
+- proxy method overrides get loaded during app initialization
+
+## [0.5.1] - 2022-04-20
+
+- `ActiveRecord` scopes are now documented
+
+## [0.5.0] - 2022-04-19
+
+- Add some static comments to the schema file to improve general Rails intellisense
+- Rename schema file from `app/models/annotate_solargraph_schema.rb` to `.annotate-solargraph-schema`
+- Generate schema file as a regular ruby file
+- Add `yard` and `solargraph` as dependencies
+- Add `.solargraph.yml` to the installation generator
+
 ## [0.4.0] - 2022-04-17
 
 - Annotations get saved to a schema file by default `app/models/annotate_solargraph_schema.rb`

data/Gemfile

@@ -5,6 +5,7 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in rails-annotate-solargraph.gemspec
 gemspec
 
+gem 'byebug'
 gem 'debug'
 gem 'git'
 gem "minitest", "~> 5.0"

data/Gemfile.lock

@@ -1,8 +1,10 @@
 PATH
   remote: .
   specs:
-    rails-annotate-solargraph (0.4.0)
+    rails-annotate-solargraph (0.5.2)
       rails (>= 5.0, < 8.0)
+      solargraph
+      yard
 
 GEM
   remote: https://rubygems.org/
@@ -76,6 +78,7 @@ GEM
     backport (1.2.0)
     benchmark (0.2.0)
     builder (3.2.4)
+    byebug (11.1.3)
     concurrent-ruby (1.1.10)
     crass (1.0.6)
     debug (1.5.0)
@@ -219,6 +222,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  byebug
   debug
   git
   minitest (~> 5.0)

data/lib/generators/annotate/solargraph/install_generator.rb

@@ -1,3 +1,8 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'set'
+
 module Annotate
   module Solargraph
     module Generators
@@ -8,6 +13,17 @@ module Annotate
         # copy rake tasks
         def copy_tasks
           template ::Rails::Annotate::Solargraph::RAKEFILE_NAME, ::File.join('lib', 'tasks', ::Rails::Annotate::Solargraph::RAKEFILE_NAME)
+          template ::Rails::Annotate::Solargraph::SCHEMA_FILE_NAME, ::Rails::Annotate::Solargraph::SCHEMA_RAILS_PATH
+
+          solargraph_config_file = ::File.join(::Rails.root, ::Rails::Annotate::Solargraph::SOLARGRAPH_FILE_NAME)
+          system 'solargraph config' unless ::File.exist? solargraph_config_file
+          solargraph_config = ::YAML.load_file solargraph_config_file
+          solargraph_config['include'] = solargraph_config['include'] || []
+          solargraph_config['include'].unshift ::Rails::Annotate::Solargraph::SCHEMA_RAILS_PATH
+          # make sure there are no duplicated entries
+          solargraph_config['include'] = solargraph_config['include'].to_set.to_a
+
+          ::File.write(solargraph_config_file, solargraph_config.to_yaml)
         end
       end
     end

data/lib/generators/annotate/solargraph/templates/.annotate_solargraph_schema

@@ -0,0 +1,69 @@
+# This is a dummy file generated by `rails-annotate-solargraph`
+# to extend solargraph's understanding of your Rails app.
+# You should probably add it to `.gitignore`
+
+# Some static comments to fill a few gaps
+# in Rails comprehension.
+
+class ActionController::Base
+  include ActionController::MimeResponds
+  include ActionController::Redirecting
+  include ActionController::Cookies
+  include AbstractController::Rendering
+  extend ActiveSupport::Callbacks::ClassMethods
+  extend ActiveSupport::Rescuable::ClassMethods
+  extend AbstractController::Callbacks::ClassMethods
+  extend ActionController::RequestForgeryProtection::ClassMethods
+end
+class ActiveRecord::Base
+  extend ActiveRecord::Reflection::ClassMethods
+  extend ActiveModel::SecurePassword::ClassMethods
+  extend ActiveModel::Attributes::ClassMethods
+  include ActiveModel::Attributes
+  include ActiveModel::Dirty
+  extend ActiveRecord::Validations::ClassMethods
+  include ActiveRecord::Validations
+  extend ActiveModel::Validations::ClassMethods
+  include ActiveModel::Validations
+  extend ActiveRecord::Calculations
+  extend ActiveRecord::Batches
+  extend ActiveRecord::QueryMethods
+  extend ActiveRecord::FinderMethods
+  extend ActiveRecord::Associations::ClassMethods
+  extend ActiveRecord::Inheritance::ClassMethods
+  extend ActiveRecord::ModelSchema::ClassMethods
+  extend ActiveRecord::Transactions::ClassMethods
+  extend ActiveRecord::Scoping::Named::ClassMethods
+  include ActiveRecord::Persistence
+
+<% (ActiveRecord::Callbacks::CALLBACKS rescue []).each do |callback| -%>
+  # Registers a callback to be called <%= callback.to_s.gsub('_', ' ') %>.
+  # See `ActiveRecord::Callbacks` for more information.
+  # @return [void]
+  def self.<%= callback %>(*args, &block); end
+<% end -%>
+
+end
+class Rails
+  # @return [Rails::Application]
+  def self.application; end
+end
+class Rails::Application
+  # @return [ActionDispatch::Routing::RouteSet]
+  def routes; end
+end
+class ActionDispatch::Routing::Mapper
+  include ActionDispatch::Routing::Mapper::Base
+  include ActionDispatch::Routing::Mapper::HttpHelpers
+  include ActionDispatch::Routing::Mapper::Redirection
+  include ActionDispatch::Routing::Mapper::Scoping
+  include ActionDispatch::Routing::Mapper::Concerns
+  include ActionDispatch::Routing::Mapper::Resources
+  include ActionDispatch::Routing::Mapper::CustomUrls
+end
+class ActionDispatch::Routing::RouteSet
+  # @yieldself [ActionDispatch::Routing::Mapper]
+  def draw; end
+end
+
+# Dynamically generated documentation

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

@@ -5,11 +5,13 @@ if ::Rails.env.development?
     namespace :solargraph do
       desc "Add YARD comments documenting the models' schemas"
       task generate: :environment do
+        ::ENV['ANNOTATE_SOLARGRAPH_RAKE_TASK'] = 'true'
         ::Rails::Annotate::Solargraph.generate
       end
 
       desc "Remove YARD comments documenting the models' schemas"
       task remove: :environment do
+        ::ENV['ANNOTATE_SOLARGRAPH_RAKE_TASK'] = 'true'
         ::Rails::Annotate::Solargraph.remove
       end
     end
@@ -19,6 +21,7 @@ if ::Rails.env.development?
       next unless ::Rake::Task.task_defined?(task)
 
       ::Rake::Task[task].enhance do
+        system 'yard gems' unless ENV['TEST']
         ::Rake::Task['annotate:solargraph:generate'].invoke
       end
     end

data/lib/rails/annotate/overrides.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class ActiveRecord::Base
+  class << self
+    alias orig_scope scope
+
+    def scope(*args, **kwargs, &block)
+      return orig_scope(*args, **kwargs, &block) unless ::ENV['ANNOTATE_SOLARGRAPH_RAKE_TASK']
+
+      file_path, scope_line_number = caller.first.split(':')
+      scope_line_number = scope_line_number.to_i
+      scope_name = args.first
+      scope_proc = args[1]
+      proc_parameters = scope_proc.respond_to?(:parameters) ? scope_proc.parameters.map(&:last) : []
+      scope_line = nil
+      scope_model_class = self
+
+      ::File.open(file_path) do |file|
+        file.each_line.with_index(1) do |line, current_line_number|
+          next unless current_line_number == scope_line_number
+
+          scope_line = line.strip
+          break
+        end
+      end
+
+      ::Rails::Annotate::Solargraph::Model.add_scope(scope_name.to_sym, scope_model_class, proc_parameters, scope_line)
+
+      orig_scope(*args, **kwargs, &block)
+    end
+  end
+end

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

@@ -8,33 +8,48 @@ module Rails
       class Model
         using TerminalColors::Refinement
 
+        Scope = ::Struct.new(:name, :model_class, :proc_parameters, :definition, keyword_init: true)
+
         # @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
 
+        # @return [Hash{Symbol => String}]
+        TYPE_MAP = {
+          float: 'BigDecimal',
+          decimal: 'BigDecimal',
+          integer: 'Integer',
+          datetime: 'ActiveSupport::TimeWithZone',
+          date: 'Date',
+          string: 'String',
+          boolean: 'Boolean',
+          text: 'String',
+          jsonb: 'Hash',
+          citext: 'String',
+          json: 'Hash',
+          bigint: 'Integer',
+          uuid: 'String',
+          inet: 'IPAddr'
+        }
+        TYPE_MAP.default = 'Object'
+        TYPE_MAP.freeze
+
         class << self
-          # @param type [Symbol, String, nil]
-          # @return [String]
-          def active_record_type_to_yard(type)
-            case type&.to_sym
-            when :float
-              ::Float.to_s
-            when :integer
-              ::Integer.to_s
-            when :decimal
-              ::BigDecimal.to_s
-            when :datetime, :timestamp, :time
-              ::Time.to_s
-            when :json, :jsonb
-              ::Hash.to_s
-            when :date
-              ::Date.to_s
-            when :text, :string, :binary, :inet, :uuid
-              ::String.to_s
-            when :boolean
-              'Boolean'
-            else
-              ::Object.to_s
-            end
+          # @return [Hash{Class => Array<Rails::Annotate::Solargraph::Model::Scope>}]
+          def scopes
+            @scopes ||= {}
+            @scopes
+          end
+
+          # @param name [Symbol]
+          # @param model_class [Class]
+          # @param proc_parameters [Array<Symbol>]
+          # @param definition [String]
+          def add_scope(name, model_class, proc_parameters, definition)
+            scope = Scope.new(name: name, model_class: model_class, proc_parameters: proc_parameters, definition: definition)
+            @scopes ||= {}
+            @scopes[model_class] ||= []
+            @scopes[model_class] << scope
+            @scopes[model_class].sort_by! { |scope| scope.name }
           end
 
           # @param klass [Class]
@@ -67,8 +82,7 @@ module Rails
         # @param klass [Class]
         def initialize(klass)
           @klass = klass
-          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)
+          @file_name = CONFIG.schema_file? ? SCHEMA_RAILS_PATH : ::File.join(::Rails.root, MODEL_DIR, "#{klass.to_s.underscore}.rb")
         end
 
         # @return [String]
@@ -101,7 +115,6 @@ module Rails
           end
 
           return new_file_content unless write
-          # debugger
           return new_file_content if old_content == new_file_content
 
           write_file @file_name, new_file_content
@@ -128,16 +141,55 @@ module Rails
           doc_string = ::String.new
           doc_string << <<~DOC
             #{annotation_start}
-            # @!parse
+            ##{parse_clause}
             #   class #{@klass} < #{@klass.superclass}
           DOC
 
+          document_scopes(doc_string)
+          document_relations(doc_string)
+          document_fields(doc_string)
+
+          doc_string << <<~DOC.chomp
+            #   end
+            # #{annotation_end}
+          DOC
+
+          # uncomment the generated annotations if they're saved in the schema file
+          return doc_string.gsub(/^#\ {3}/, '').gsub(/^#\n/, "\n") if CONFIG.schema_file?
+
+          doc_string
+        end
+
+        private
+
+        # @param doc_string [String]
+        # @return [void]
+        def document_scopes(doc_string)
+          self.class.scopes[@klass]&.each do |scope|
+            doc_string << <<~DOC
+              #     # Scope `#{scope.name.inspect}`.
+              #     #
+              #     #     #{scope.definition}
+              #     #
+              #     # @return [Array<#{@klass}>, nil]
+              #     def self.#{scope.name}(#{scope.proc_parameters.join(', ')}); end
+            DOC
+          end
+        end
+
+        # @param doc_string [String]
+        # @return [void]
+        def document_relations(doc_string)
           @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
+        end
 
+        # @param doc_string [String]
+        # @return [void]
+        def document_fields(doc_string)
           @klass.attribute_types.each do |name, attr_type|
             doc_string << <<~DOC
               #     # Database column `#{@klass.table_name}.#{name}`, type: `#{attr_type.type}`.
@@ -148,14 +200,14 @@ module Rails
               #     def #{name}; end
             DOC
           end
-
-          doc_string << <<~DOC.chomp
-            #   end
-            # #{annotation_end}
-          DOC
         end
 
-        private
+        # @return [String, nil]
+        def parse_clause
+          return if CONFIG.schema_file?
+
+          " @!parse\n#"
+        end
 
         # @param file_name [String]
         # @return [String]
@@ -344,7 +396,7 @@ module Rails
           return attr_type.coder.object_class.to_s if attr_type.respond_to?(:coder) && attr_type.coder.respond_to?(:object_class)
           return 'Object' if attr_type.respond_to?(:coder) && attr_type.coder.is_a?(::ActiveRecord::Coders::JSON)
 
-          self.class.active_record_type_to_yard(attr_type.type)
+          TYPE_MAP[attr_type.type]
         end
       end
     end

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

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

data/lib/rails/annotate/solargraph.rb

@@ -8,6 +8,12 @@ require_relative "solargraph/configuration"
 require_relative "solargraph/terminal_colors"
 require_relative "solargraph/model"
 
+begin
+  require_relative "overrides"
+rescue
+  nil
+end
+
 module Rails
   module Annotate
     module Solargraph
@@ -23,7 +29,11 @@ module Rails
       # @return [String]
       SCHEMA_CLASS_NAME = 'AnnotateSolargraphSchema'
       # @return [String]
-      SCHEMA_FILE_NAME = "annotate_solargraph_schema.rb"
+      SOLARGRAPH_FILE_NAME = '.solargraph.yml'
+      # @return [String]
+      SCHEMA_FILE_NAME = '.annotate_solargraph_schema'
+      # @return [String]
+      SCHEMA_RAILS_PATH = SCHEMA_FILE_NAME
 
       class << self
         # @return [Array<String>] Array of changed files.
@@ -56,13 +66,10 @@ 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)
+          schema_file = ::File.join ::Rails.root, SCHEMA_RAILS_PATH
+          return if ::File.exist?(schema_file)
 
-          ::FileUtils.touch(schema_file)
-          ::File.write schema_file, <<~SCHEMA
-            module AnnotateSolargraphSchema; end
-          SCHEMA
+          system 'rails g annotate:solargraph:install'
         end
 
         # @param method [Symbol] Name of the method that will be called on every loaded Model
@@ -74,6 +81,7 @@ module Rails
           changed_files = []
           model_files = ::Dir[::File.join(::Rails.root, MODEL_DIR, '**/*.rb')].map { |file| file.sub("#{::Rails.root}/", '') }.to_set
 
+          require_relative "overrides"
           ::Rails.application.eager_load!
           model_classes.each do |subclass|
             subclass_file = ::File.join MODEL_DIR, "#{subclass.to_s.underscore}.rb"

data/rails-annotate-solargraph.gemspec

@@ -31,6 +31,8 @@ Gem::Specification.new do |spec|
 
   # Uncomment to register a new dependency of your gem
   spec.add_dependency 'rails', ">= 5.0", '< 8.0'
+  spec.add_dependency 'solargraph'
+  spec.add_dependency 'yard'
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-annotate-solargraph
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Mateusz Drewniak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-04-17 00:00:00.000000000 Z
+date: 2022-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -30,6 +30,34 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: solargraph
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Annotate ActiveRecord models with schema comments formatted in YARD that
   are compatible with Solargraph.
 email:
@@ -53,7 +81,9 @@ files:
 - bin/console
 - bin/setup
 - lib/generators/annotate/solargraph/install_generator.rb
+- lib/generators/annotate/solargraph/templates/.annotate_solargraph_schema
 - lib/generators/annotate/solargraph/templates/rails_annotate_solargraph.rake
+- lib/rails/annotate/overrides.rb
 - lib/rails/annotate/solargraph.rb
 - lib/rails/annotate/solargraph/configuration.rb
 - lib/rails/annotate/solargraph/model.rb