rails-annotate-solargraph 0.3.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ca6f0073923760a583abb52af713540b2f53cf6e8dd896584e3a76b97444c8b
-  data.tar.gz: a07141ca737ee0c60153cabd5e28540d3507ba09401b4cc31d30ea491bc32eb2
+  metadata.gz: a3f9d275d9de0b0a37b8fae4f7f65ec2121ca25990ccfcc75e246e4c28711531
+  data.tar.gz: 1467357d585931d57d440d964a54ead827a964112757ef53a3253c86ac5d3790
 SHA512:
-  metadata.gz: f3a40df235de87414059053670f344e0e6606b9538ecba40b7fbb2c849c07f8009e5cec055e485033bae5529bce9146d2369d76b8a6ab4288664703bef29da2f
-  data.tar.gz: d920e8b59c64f57d22fba128b4db1acffd88b718799e24e2f361d43e99ae6505258faa2665f57fafdee9d9cd6d4dc47231c9e5e7bb99a7e687707c2642e211e5
+  metadata.gz: d93389956d525b72fff9a08ab11bf48b65733fe3eed85c114fee771be0733b27205521d49512c8d3403a5ab1e6dbae699e40d434a10e642ec6eadc4426b42908
+  data.tar.gz: 225b3e7c0937c65940a7020162a0d2c2d91c1e83420a300d4d0740b187e16ca7119f554e61f73d20ce79fcb5e26a36b99051d8d0cfd3a17afd7c3e366e5cb977

data/.vscode/settings.json

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

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [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`
+
 ## [0.3.0] - 2022-04-17
 
 - `has_many :through` and `has_one :through` relations get documented

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.3.0)
+    rails-annotate-solargraph (0.5.1)
       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/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/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

@@ -19,6 +19,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,30 @@
+# frozen_string_literal: true
+
+class ActiveRecord::Base
+  class << self
+    alias orig_scope scope
+
+    def scope(*args, **kwargs, &block)
+      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/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,44 +1,72 @@
 # 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
+        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 [Hash{Class => Array<Rails::Annotate::Solargraph::Model::Scope>}]
+          attr_reader :scopes
+
+          # @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]
           # @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
+          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
 
@@ -51,7 +79,22 @@ module Rails
         # @param klass [Class]
         def initialize(klass)
           @klass = klass
-          @file_name = ::File.join(::Rails.root, MODEL_DIR, "#{klass.to_s.underscore}.rb")
+          @file_name = CONFIG.schema_file? ? SCHEMA_RAILS_PATH : ::File.join(::Rails.root, MODEL_DIR, "#{klass.to_s.underscore}.rb")
+        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]
@@ -69,7 +112,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
@@ -79,8 +121,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
@@ -93,17 +137,56 @@ module Rails
         def annotation
           doc_string = ::String.new
           doc_string << <<~DOC
-            #{ANNOTATION_START}
-            # @!parse
+            #{annotation_start}
+            ##{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}`.
@@ -114,14 +197,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]
@@ -133,6 +216,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
@@ -309,7 +393,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.3.0'
+      VERSION = '0.5.1'
     end
   end
 end

data/lib/rails/annotate/solargraph.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 require 'set'
+require 'fileutils'
 
 require_relative "solargraph/version"
 require_relative "solargraph/configuration"
 require_relative "solargraph/terminal_colors"
 require_relative "solargraph/model"
 
+
 module Rails
   module Annotate
     module Solargraph
@@ -19,11 +21,20 @@ module Rails
       CONFIG = Configuration.new
       # @return [Set<Symbol>]
       VALID_MODIFICATION_METHODS = ::Set[:annotate, :remove_annotation].freeze
+      # @return [String]
+      SCHEMA_CLASS_NAME = 'AnnotateSolargraphSchema'
+      # @return [String]
+      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.
         def generate
           title 'Generating model schema annotations'
+          create_schema_file
           modify_models :annotate
         end
 
@@ -49,6 +60,13 @@ module Rails
 
         include TerminalColors
 
+        def create_schema_file
+          schema_file = ::File.join ::Rails.root, SCHEMA_RAILS_PATH
+          return if ::File.exist?(schema_file)
+
+          system 'rails g annotate:solargraph:install'
+        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)
@@ -58,6 +76,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.3.0
+  version: 0.5.1
 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