qdocs 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc6b3ccc77bc958c324f4cdc463febbcd6337e7c6b39a51e55f215c187167d80
-  data.tar.gz: 503a6012c888d1626a834f1ab95d2fbc194ca9193943ea1595d4e9c732bfd038
+  metadata.gz: 3505075b7d10b99e85d446e53362b068a6e3f3d124ce13ab2ff3868be4ee6b2a
+  data.tar.gz: 3744fc4e1076d4c38a850dd98eb1c6a3cdf81cef6a0c9d2f9ff7c8c55790d6f7
 SHA512:
-  metadata.gz: 3066dea2b451986c417f12ed8e437c0d6131068a546d30969a305be55cc63ec0044f3ec09add1d650356e321810546a49a84c23ecc9a0219fb408d27deddf9b2
-  data.tar.gz: 679cd7f630fd15b4026646cfb60bbb1692fc8ddcbceb8febecf3585a75e86c705fd08c4399fa3556bcdb379829240dc0254f949e242501988c4760530c8d52e6
+  metadata.gz: 80c407034f987fd1db6ef01b159fe14bb21b8a91cf48c7a1f77e7c97e1b3d0d9370a0ba4273a530989b4c450af304ab8f9bed3af93ae5dfa9e9623c0fabde8cb
+  data.tar.gz: 199ef4aa13ea9665d8643cd58c1cdd4cd69fb79e58cfb30b54157633f291e9784dcc263003f20ca0432277331f111485fc2a34a18a14f5ee9a77be1f20042a26

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    qdocs (0.1.0)
+    qdocs (0.2.0)
       method_source (~> 1)
       rack (> 1)
 

data/README.md

@@ -1,15 +1,20 @@
 # Qdocs
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/qdocs`. To experiment with that code, run `bin/console` for an interactive prompt.
+Qdocs is a very lightweight language intelligence server, which provides runtime information about constants and methods. It currently supports:
+
+- Providing detailed information about instance and singleton methods for Ruby constants (eg. Classes and Modules)
+- Querying a constant's instance and singleton methods by regular expression, returning the methods whose names match the given pattern
+- Providing detailed information about active record attributes, if the constant being queried is an ActiveRecord model
+
+It has minimal dependencies (probably nothing extra, if your application uses rails or another common web framework)
 
-TODO: Delete this and the text above, and describe your gem
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'qdocs'
+gem 'qdocs', require: false
 ```
 
 And then execute:
@@ -22,7 +27,67 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+This gem offers CLI usage, or server usage:
+
+#### Server usage:
+`$ qdocs --server`
+
+
+`$ curl 'http://localhost:8080/?input=User%2Efind'`
+
+#### CLI usage
+
+```
+$ qdocs 'Set#length'
+{
+  "original_input": "Set#length",
+  "constant": {
+    "name": "Set",
+    "type": "Class"
+  },
+  "query_type": "instance_method",
+  "attributes": {
+    "defined_at": "/Users/josephjohansen/.rvm/rubies/ruby-2.7.1/lib/ruby/2.7.0/set.rb:151",
+    "source": "def size\n  @hash.size\nend\n",
+    "arity": 0,
+    "parameters": {
+    },
+    "comment": "# Returns the number of elements.",
+    "name": "length",
+    "belongs_to": "Set",
+    "super_method": null
+  }
+}
+```
+**also provides support for constants which are recognised to be ActiveRecord models:**
+
+```
+$ curl 'http://localhost:7593/?input=User%2Femail%2F'
+{
+  "constant": {
+    "name": "User",
+    "type": "Class"
+  },
+  "query_type": "methods",
+  "attributes": {
+    "constant": "User",
+    "singleton_methods": [
+      "find_by_unconfirmed_email_with_errors"
+    ],
+    "instance_methods": [
+      "postpone_email_change?",
+      "postpone_email_change_until_confirmation_and_regenerate_confirmation_token",
+      "send_email_changed_notification?",
+      "send_verification_email"
+    ]
+  }
+}
+
+```
+
+#### Further usage examples:
+
+`$ qdocs --help` 
 
 ## Development
 

data/lib/qdocs.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-require 'method_source'
+require "method_source"
 require_relative "qdocs/version"
+require "pathname"
 
 module Qdocs
   class UnknownClassError < StandardError; end
@@ -41,102 +42,152 @@ module Qdocs
     rescue NameError
       raise UnknownClassError, "Unknown constant #{const}"
     end
-  end
-
-  class Const
-    include Helpers
-
-    def show(const)
-      const = const.to_s
-      constant = find_constant const
-
-      const_sl = Object.const_source_location const
 
+    def render_response(const, type, attrs)
       {
-        source_location: source_location_to_str(const_sl),
-        instance_methods: own_methods(constant.instance_methods).sort,
-        singleton_methods: own_methods(constant.methods).sort,
+        original_input: @original_input,
+        constant: {
+          name: const.name,
+          type: const.class.name,
+        },
+        query_type: type,
+        attributes: attrs,
       }
     end
   end
 
-  class Method
-    include Helpers
+  module Base
+    class Const
+      include Helpers
 
-    def index(const, pattern)
-      constant = find_constant const
-      {
-        constant: constant,
-        singleton_methods: own_methods(constant.methods.grep(pattern)).sort,
-        instance_methods: own_methods(constant.instance_methods.grep(pattern)).sort,
-      }
+      def initialize(original_input)
+        @original_input = original_input
+      end
+
+      def show(const)
+        const = const.to_s
+        constant = find_constant const
+        yield constant if block_given?
+
+        const_sl = Object.const_source_location const
+
+        render_response(constant, :constant, {
+          source_location: source_location_to_str(const_sl),
+          instance_methods: own_methods(constant.instance_methods).sort,
+          singleton_methods: own_methods(constant.methods).sort,
+        })
+      end
     end
 
-    def show(const, meth, type)
-      constant = begin
-                   find_constant(const)
-                 rescue UnknownClassError
-                   abort "Unknown class #{const.inspect}"
-                 end
-      method = case meth
-               when Symbol, String
-                 method_method = case type
-                                 when :instance
-                                   :instance_method
-                                 when :singleton, :class
-                                   :method
-                                 else
-                                   raise UnknownMethodTypeError, "Unknown method type #{type}"
-                                 end
-
-                 begin
-                   constant.send method_method, meth
-                 rescue NameError
-                   raise UnknownMethodError, "No method #{meth.inspect} for #{constant.inspect}. Did you mean #{constant.inspect}/#{meth}/ ?"
-                 end
-               when Method
-                 meth
-               else
-                 raise InvalidArgumentError, "#{meth.inspect} must be of type Symbol, String, or Method"
-               end
-
-      parameters = params_to_hash(method.parameters)
-      src = method.source rescue nil
-      source = if src
-                 lines = src.lines
-                 first_line = lines.first
-                 indent_amount = first_line.length - first_line.sub(/^\s*/, '').length
-                 lines.map { |l| l[indent_amount..-1] }.join
-               end
+    class Method
+      include Helpers
 
-      {
-        defined_at: source_location_to_str(method.source_location),
-        source: source,
-        arity: method.arity,
-        parameters: parameters,
-        comment: (method.comment.strip rescue nil),
-        name: method.name,
-        belongs_to: method.owner,
-        super_method: method.super_method,
-      }
+      def initialize(original_input)
+        @original_input = original_input
+      end
+
+      def index(const, pattern)
+        constant = find_constant const
+
+        yield constant if block_given?
+
+        render_response(constant, :methods, {
+          constant: constant,
+          singleton_methods: own_methods(constant.methods.grep(pattern)).sort,
+          instance_methods: own_methods(constant.instance_methods.grep(pattern)).sort,
+        })
+      end
+
+      def show(const, meth, type)
+        constant = find_constant(const)
+
+        yield constant if block_given?
+
+        method = case meth
+          when Symbol, String
+            method_method = case type
+              when :instance
+                :instance_method
+              when :singleton, :class
+                :method
+              else
+                raise UnknownMethodTypeError, "Unknown method type #{type}"
+              end
+
+            begin
+              constant.send method_method, meth
+            rescue NameError
+              raise UnknownMethodError, "No method #{meth.inspect} for #{constant}. Did you mean #{constant}/#{meth}/ ?"
+            end
+          when ::Method
+            meth
+          else
+            raise InvalidArgumentError, "#{meth.inspect} must be of type Symbol, String, or Method"
+          end
+
+        parameters = params_to_hash(method.parameters)
+        src = method.source rescue nil
+        source = if src
+            lines = src.lines
+            first_line = lines.first
+            indent_amount = first_line.length - first_line.sub(/^\s*/, "").length
+            lines.map { |l| l[indent_amount..-1] }.join
+          end
+        sup = method.super_method
+
+        render_response(constant, method_method, {
+          defined_at: source_location_to_str(method.source_location),
+          source: source,
+          arity: method.arity,
+          parameters: parameters,
+          comment: (method.comment.strip rescue nil),
+          name: method.name,
+          belongs_to: method.owner,
+          super_method: sup ? Handler::Method.new.show(sup.owner, sup, type) : nil,
+        })
+      end
     end
   end
 
   METHOD_REGEXP = /(?:[a-zA-Z_]+|\[\])[?!=]?/.freeze
   CONST_REGEXP = /[[:upper:]]\w*(?:::[[:upper:]]\w*)*/.freeze
 
+  def self.load_env(dir_level = nil)
+    check_dir = dir_level || ["."]
+    project_top_level = Pathname(File.join(*check_dir, "Gemfile")).exist? ||
+                        Pathname(File.join(*check_dir, ".git")).exist?
+    if project_top_level && Pathname(File.join(*check_dir, "config", "environment.rb")).exist?
+      require File.join(*check_dir, "config", "environment.rb")
+    elsif project_top_level
+      # no op - no env to load
+    else
+      dir_level ||= []
+      dir_level << ".."
+      Qdocs.load_env(dir_level)
+    end
+  end
+
+  load_env
+
+  Handler = if Object.const_defined? :ActiveRecord
+      require "qdocs/active_record"
+      Qdocs::ActiveRecord
+    else
+      Qdocs::Base
+    end
+
   def self.lookup(input)
     case input
     when /\A([[:lower:]](?:#{METHOD_REGEXP})?)\z/
-      Qdocs::Method.new.show(Object, $1, :instance)
+      Handler::Method.new(input).show(Object, $1, :instance)
     when /\A(#{CONST_REGEXP})\.(#{METHOD_REGEXP})\z/
-      Qdocs::Method.new.show($1, $2, :singleton)
+      Handler::Method.new(input).show($1, $2, :singleton)
     when /\A(#{CONST_REGEXP})#(#{METHOD_REGEXP})\z/
-      Qdocs::Method.new.show($1, $2, :instance)
+      Handler::Method.new(input).show($1, $2, :instance)
     when /\A(#{CONST_REGEXP})\z/
-      Qdocs::Const.new.show($1)
+      Handler::Const.new(input).show($1)
     when %r{\A(#{CONST_REGEXP})/([^/]+)/\z}
-      Qdocs::Method.new.index($1, Regexp.new($2))
+      Handler::Method.new(input).index($1, Regexp.new($2))
     else
       raise UnknownPatternError, "Unrecognised pattern #{input}"
     end

data/lib/qdocs/active_record.rb

@@ -0,0 +1,98 @@
+module Qdocs
+  module ActiveRecord
+    module Helpers
+      def active_record_attributes_for(col)
+        if col.is_a? ::ActiveRecord::ConnectionAdapters::NullColumn
+          raise UnknownMethodError, "Unknown attribute #{col.name}"
+        end
+
+        {
+          type: col.sql_type_metadata&.type,
+          comment: col.comment,
+          default: col.default,
+          null: col.null,
+          default_function: col.default_function,
+        }
+      end
+
+      def if_active_record(constant)
+        if Object.const_defined?("::ActiveRecord::Base") && constant < ::ActiveRecord::Base
+          yield constant
+        end
+      end
+    end
+
+    class Const < Qdocs::Base::Const
+      include ActiveRecord::Helpers
+
+      def show(const)
+        database_attributes = {}
+        constant = nil
+        resp = super do |con|
+          if_active_record(con) do |klass|
+            constant = klass
+            klass.columns.each do |col|
+              active_record_attributes_for col
+            end
+          end
+        end
+
+        if constant
+          {
+            **resp,
+            type: :active_record_class,
+            attributes: {
+              **resp[:attributes],
+              database_attributes: database_attributes,
+            },
+          }
+        else
+          resp
+        end
+      end
+    end
+
+    class Method < Qdocs::Base::Method
+      include ActiveRecord::Helpers
+
+      def index(const, pattern)
+        database_attributes = {}
+        attrs = super do |constant|
+          if_active_record(constant) do |klass|
+            klass.columns.each do |col|
+              next unless col.name.to_s.match? pattern
+
+              database_attributes[col.name.to_sym] = active_record_attributes_for col
+            end
+          end
+        end
+
+        if database_attributes.empty?
+          attrs
+        else
+          { **attrs, database_attributes: database_attributes }
+        end
+      end
+
+      def show(const, meth, type)
+        constant = []
+        super do |klass|
+          constant << klass
+        end
+      rescue UnknownMethodError => e
+        if constant[0] && meth && type == :instance
+          if_active_record(constant[0]) do |klass|
+            m = meth.is_a?(::Method) ? (meth.name rescue nil) : meth
+            return render_response(
+                     klass,
+                     :active_record_attribute,
+                     active_record_attributes_for(klass.column_for_attribute(m))
+                   )
+          end
+        end
+
+        raise e
+      end
+    end
+  end
+end

data/lib/qdocs/server.rb

@@ -12,6 +12,11 @@ module Qdocs
       else
         [404, { "Content-Type" => "text/html; charset=utf-8" }, ["Not Found"]]
       end
+    rescue Qdocs::UnknownClassError,
+           Qdocs::UnknownMethodTypeError,
+           Qdocs::UnknownMethodError,
+           Qdocs::UnknownPatternError => e
+      [404, { "Content-Type" => "text/html; charset=utf-8" }, ["Not found: #{e.message}"]]
     rescue => e
       [500, { "Content-Type" => "text/html; charset=utf-8" }, ["Error: #{e.message}"]]
     end
@@ -20,4 +25,4 @@ end
 
 handler = Rack::Handler::WEBrick
 
-handler.run Qdocs::Server.new
+handler.run Qdocs::Server.new, Port: 7593 # random port, not common 8080

data/lib/qdocs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Qdocs
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qdocs
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Joseph Johansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-20 00:00:00.000000000 Z
+date: 2021-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: method_source
@@ -57,6 +57,7 @@ files:
 - bin/setup
 - exe/qdocs
 - lib/qdocs.rb
+- lib/qdocs/active_record.rb
 - lib/qdocs/server.rb
 - lib/qdocs/version.rb
 - qdocs.gemspec