qdocs 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75a08fcc7bf5ea74395c1b0f2bc6ec49e1716379a5d153261653442bcba0a010
-  data.tar.gz: 7d8c561702a327a76be14139f0e39e8ba9740be8d30d9eb320cfeb60502c454b
+  metadata.gz: 9c361421b501da1e4ae6c3cea59c9b28c3a5f8b50b2e3b4bf519d8b5ab97cafb
+  data.tar.gz: df3a642f6604fc8ae7c6a086a19e8178a7b3f48b119c5b6b4b9470e6a054edac
 SHA512:
-  metadata.gz: 6c2a3550627278b51b4743a18b781b71988d8cd2ed4025245414548bdc1dcbe9f3d5e73b71b8d94fba39927bef76db6f378463d6ad901acc6e397b45690e695e
-  data.tar.gz: 63fc2b5e5a0ea435bf0f7d72eb3fce8a381dfc9dd8c0d6707f84e7b95b1c9b77d65a0d3556531eefdd5a6129fb16e3ef7c32f461cacbaaf438a6235e9e3ae1b4
+  metadata.gz: 035d39b7f119206e715a9134c97949eb598144b2eb06cd35ca816f179948cd89b2e38336c2574dbe4e7975c319dda6ce8d74199f77429060cefd45fbe646131c
+  data.tar.gz: 7091c36e72815b43cb3c0b218fa3e1cbb8175a79db535bd1ebd11a59bed08141563c220db0ae5d1b4787971b4c4d5a7886679d6288c23a1c9dd470a1861e754f

data/Gemfile.lock

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

data/README.md

@@ -27,13 +27,20 @@ Or install it yourself as:
 
 ## Usage
 
-This gem offers CLI usage, or server usage:
+This gem offers CLI usage, text editor integration, or viewing in a browser:
 
-#### Server usage:
+#### Starting a server manually:
 `$ qdocs --server`
 
 
-`$ curl 'http://localhost:8080/?input=User%2Efind'`
+`$ curl 'http://localhost:7593/?input=User%2Efind' # view JSON response`
+
+or view it in your browser, to be able to navigate through a GUI:
+
+`$ open 'http://localhost:7593/?input=User%2Efind'`
+
+<img width="1346" alt="Screenshot 2021-05-24 at 11 30 29" src="https://user-images.githubusercontent.com/43235608/119334821-771c1980-bc83-11eb-8027-af9c31338885.png">
+
 
 #### CLI usage
 
@@ -62,33 +69,42 @@ $ qdocs 'Set#length'
 **also provides support for constants which are recognised to be ActiveRecord models:**
 
 ```
-$ curl 'http://localhost:7593/?input=User%2Femail%2F'
+$ curl 'http://localhost:7593/?input=User%2Eemail'
 {
+  "original_input": "User#id",
   "constant": {
     "name": "User",
     "type": "Class"
   },
-  "query_type": "methods",
+  "query_type": "instance_method",
   "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"
-    ]
+    "defined_at": "~/.rvm/gems/ruby-2.7.1/gems/activerecord-6.0.3.6/lib/active_record/attribute_methods/primary_key.rb:18",
+    "source": "def id\n  _read_attribute(@primary_key)\nend\n",
+    "arity": 0,
+    "parameters": {},
+    "comment": "# Returns the primary key column's value.",
+    "name": "id",
+    "belongs_to": "ActiveRecord::AttributeMethods::PrimaryKey",
+    "super_method": null
   }
 }
 
 ```
 
+#### Editor integration
+
+See below
+
 #### Further usage examples:
 
 `$ qdocs --help` 
 
+## Editor integration
+
+Feel free to add others! 
+
+- [Vim](https://github.com/johansenja/qdocs-vim) 
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -97,7 +113,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/qdocs.
+Bug reports and pull requests are welcome on GitHub at https://github.com/johansenja/qdocs.
 
 ## License
 

data/lib/qdocs.rb

@@ -13,6 +13,8 @@ module Qdocs
 
   class UnknownPatternError < StandardError; end
 
+  class InvalidArgumentError < StandardError; end
+
   module Helpers
     def source_location_to_str(source_location)
       if source_location && source_location.length == 2
@@ -44,10 +46,17 @@ module Qdocs
     end
 
     def render_response(const, type, attrs)
+      const_name = if const.is_a?(Class) || const.is_a?(Module)
+          const.name
+        elsif instance_of?(Class) || const.instance_of?(Module)
+          const.inspect
+        else
+          const.to_s
+        end
       {
         original_input: @original_input,
         constant: {
-          name: const.name,
+          name: const_name,
           type: const.class.name,
         },
         query_type: type,
@@ -71,11 +80,43 @@ module Qdocs
 
         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,
-        })
+        if constant.instance_of?(Class) ||
+           constant.instance_of?(Module)
+          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,
+            included_modules: constant.included_modules,
+            constants: constant.constants,
+            constant_type: constant.class.name,
+            inheritance_chain: build_inheritance_chain(constant).map(&:name),
+          })
+        else
+          render_response(constant, :constant, {
+            source_location: source_location_to_str(const_sl),
+            instance_methods: nil,
+            singleton_methods: nil,
+            included_modules: nil,
+            constants: nil,
+            value: constant,
+            constant_type: constant.class.name,
+            inheritance_chain: nil,
+          })
+        end
+      end
+
+      private
+
+      def build_inheritance_chain(initial)
+        chain = [initial]
+        klass = initial
+        while klass.respond_to?(:superclass)
+          break unless (sc = klass.superclass)
+
+          chain << sc
+          klass = sc
+        end
+        chain
       end
     end
 
@@ -119,7 +160,7 @@ module Qdocs
             rescue NameError
               raise UnknownMethodError, "No method #{meth.inspect} for #{constant}. Did you mean #{constant}/#{meth}/ ?"
             end
-          when ::Method
+          when ::Method, UnboundMethod
             meth
           else
             raise InvalidArgumentError, "#{meth.inspect} must be of type Symbol, String, or Method"
@@ -143,7 +184,7 @@ module Qdocs
           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,
+          super_method: sup ? Handler::Method.new(@original_input).show(sup.owner, sup, type) : nil,
         })
       end
     end

data/lib/qdocs/active_record.rb

@@ -12,11 +12,15 @@ module Qdocs
           default: col.default,
           null: col.null,
           default_function: col.default_function,
+          name: col.name,
         }
       end
 
       def if_active_record(constant)
-        if Object.const_defined?("::ActiveRecord::Base") && constant < ::ActiveRecord::Base
+        if Object.const_defined?("::ActiveRecord::Base") &&
+           constant.respond_to?(:<) &&
+           constant < ::ActiveRecord::Base &&
+           !constant.abstract_class
           yield constant
         end
       end
@@ -32,7 +36,7 @@ module Qdocs
           if_active_record(con) do |klass|
             constant = klass
             klass.columns.each do |col|
-              active_record_attributes_for col
+              database_attributes[col.name.to_sym] = active_record_attributes_for col
             end
           end
         end
@@ -70,7 +74,13 @@ module Qdocs
         if database_attributes.empty?
           attrs
         else
-          { **attrs, database_attributes: database_attributes }
+          {
+            **attrs,
+            attributes: {
+              **attrs[:attributes],
+              database_attributes: database_attributes,
+            },
+          }
         end
       end
 

data/lib/qdocs/server.rb

@@ -7,18 +7,62 @@ module Qdocs
       params = req.params
       case env["REQUEST_PATH"]
       when "/"
-        body = JSON.pretty_generate(Qdocs.lookup(params["input"]))
-        [200, { "Content-Type" => "application/json; charset=utf-8" }, [body]]
+        resp = Qdocs.lookup(params["input"])
+        # this is a bit ugly but ok 🤷
+        format = req.env.fetch("HTTP_ACCEPT", "")
+        body, content_type = case format
+          when %r{text/html}
+            require "erb"
+            template = case resp[:query_type]
+              when :methods
+                "constant/show"
+              when :instance_method, :singleton_method, :class_method, :method
+                "method/show"
+              when :active_record_attribute
+                "method/active_record_show"
+              when :constant, :active_record_class
+                "constant/show"
+              end
+            [render_html(resp, template), "text/html"]
+          else
+            [JSON.pretty_generate(resp), "application/json"]
+          end
+        [200, { "Content-Type" => "#{content_type}" }, [body]]
       else
-        [404, { "Content-Type" => "text/html; charset=utf-8" }, ["Not Found"]]
+        [404, { "Content-Type" => "text/plain; 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}"]]
+      [404, { "Content-Type" => "text/plain; charset=utf-8" }, ["Not found: #{e.message}"]]
     rescue => e
-      [500, { "Content-Type" => "text/html; charset=utf-8" }, ["Error: #{e.message}"]]
+      pp e.backtrace
+      [500, { "Content-Type" => "text/plain; charset=utf-8" }, ["Error: #{e.message}"]]
+    end
+
+    private
+
+    def render_html(resp, template)
+      layout_contents = File.read(
+        File.join(
+          __dir__,
+          "..",
+          "views",
+          "common.html.erb"
+        )
+      )
+      specific_contents = File.read(
+        File.join(
+          __dir__,
+          "..",
+          "views",
+          "#{template}.html.erb"
+        )
+      )
+      @resp, @const_name = resp, resp.dig(:constant, :name)
+      @specific_contents = ERB.new(specific_contents).result(binding)
+      ERB.new(layout_contents).result(binding)
     end
   end
 end

data/lib/qdocs/version.rb

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

data/lib/views/common.html.erb

@@ -0,0 +1,65 @@
+<html>
+  <head>
+    <title>Qdocs - <%= @resp[:original_input] %></title>
+    <style>
+      html, body {
+        font-family: monospace;
+        color: black;
+        background-color: white;
+      }
+
+      code {
+        background-color: #eee;
+        color: rebeccapurple;
+        padding: 0.5em;
+        line-height: 2em
+      }
+
+      section {
+        padding: 8px;
+        border: 1px solid #333;
+        border-radius: 3px;
+        margin: 16px 0;
+      }
+
+      th {
+        border-bottom: 1px solid #333;
+      }
+
+      th, td {
+        padding: 10px 24px;
+      }
+
+      @media(prefers-color-scheme: dark) {
+        html, body {
+          background-color: #333;
+          color: #fefefe
+        }
+
+        a {
+          color: cyan;
+        }
+
+        a:visited {
+          color: magenta
+        }
+
+        code {
+          background-color: #604e49;
+          color: #c7ff83;
+        }
+
+        section {
+          border-color: #fefefe;
+        }
+
+        th {
+          border-bottom-color: #fefefe;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <%= @specific_contents %>
+  </body>
+</html>

data/lib/views/constant/show.html.erb

@@ -0,0 +1,80 @@
+<% attributes = @resp[:attributes] %>
+<section>
+  <h1><%= CGI.escapeHTML(@const_name) %>: <%= attributes[:constant_type] %></h1>
+</section>
+<% if attributes[:source_location] %>
+  <section>
+  <% file, line_num = attributes[:source_location].split(":") %>
+  <h2>Defined at</h2>
+  <p><a href="file://<%= file %>" target="_blank"><%= file %></a>, line number <%= line_num %></p>
+  </section>
+<% end %>
+<% if attributes[:value] %>
+  <section>
+    <h2>Constant value</h2>
+    <p><%= CGI.escapeHTML(attributes[:value].to_s) %></p>
+  </section>
+<% end %>
+<% if attributes[:singleton_methods] && !attributes[:singleton_methods].empty? %>
+  <section>
+    <h2>Singleton Methods</h2>
+    <ul>
+      <% attributes[:singleton_methods].each do |m| %>
+        <li><a href="/?input=<%= @const_name %><%= CGI.escape(".")%><%= m.to_s %>"><%= m.inspect %></a></li>
+      <% end %>
+    </ul>
+  </section>
+<% end %>
+<% if attributes[:instance_methods] && !attributes[:instance_methods].empty? %>
+  <section>
+    <h2>Instance Methods</h2>
+    <ul>
+      <% attributes[:instance_methods].each do |m| %>
+        <li><a href="/?input=<%= @const_name %><%= CGI.escape("#")%><%= m.to_s %>"><%= m.inspect %></a></li>
+      <% end %>
+    </ul>
+  </section>
+<% end %>
+<% if attributes[:database_attributes] && !attributes[:database_attributes].empty? %>
+  <section>
+    <h2>Active Record columns</h2>
+    <ul>
+      <% attributes[:database_attributes].each_key do |name| %>
+        <li><a href="/?input=<%= @const_name %><%= CGI.escape("#") %><%= name.to_s %>"><%= name.inspect %></a></li>
+      <% end %>
+    </ul>
+  </section>
+<% end %>
+<% ic = attributes[:inheritance_chain] %>
+<% if ic && !ic.empty? %>
+  <section>
+    <h2>Inheritance chain</h2>
+    <ul>
+      <% ic.each do |a| %>
+        <li><a href="/?input=<%= a.to_s %>"><%= a %></a></li>
+      <% end %>
+    </ul>
+  </section>
+<% end %>
+<% included_modules = attributes[:included_modules] %>
+<% if included_modules && !included_modules.empty? %>
+  <section>
+    <h2>Included Modules</h2>
+    <ul>
+      <% included_modules.each do |m| %>
+        <li><a href="/?input=<%= m.to_s %>"><%= CGI.escapeHTML(m.to_s) %></a></li>
+      <% end %>
+    </ul>
+  </section>
+<% end %>
+<% constants = attributes[:constants] %>
+<% if constants && !constants.empty? %>
+  <section>
+    <h2>Constants</h2>
+    <ul>
+      <% constants.each do |c| %>
+        <li><a href="/?input=<%= @const_name %><%= CGI.escape("::") %><%= c %>"><%= CGI.escapeHTML(@const_name) %>::<%= CGI.escapeHTML(c.to_s) %></a></li>
+      <% end %>
+    </ul>
+  </section>
+<% end %>

data/lib/views/method/active_record_show.html.erb

@@ -0,0 +1,18 @@
+  <% attributes = @resp[:attributes] %>
+  <section>
+    <h1><a href="/?input=<%= @const_name %>"><%= @const_name %></a>#<%= attributes[:name] %></h1>
+  </section>
+  <section>
+    <dl>
+      <dt>Name</dt>
+      <dd><%= attributes[:name] %></dd>
+      <dt>Type</dt>
+      <dd><%= attributes[:type] %></dd>
+      <dt>Can be null?</dt>
+      <dd><%= attributes[:null] ? "yes" : "no" %></dd>
+      <dt>Default</dt>
+      <dd><%= attributes[:default_function] || attributes[:default] || "null" %></dd>
+      <dt>Comment</dt>
+      <dd><%= attributes[:comment] || "-" %></dd>
+    </dl>
+  </section>

data/lib/views/method/show.html.erb

@@ -0,0 +1,53 @@
+<% attributes = @resp[:attributes] %>
+<% method_type = @resp[:query_type] == :instance_method ? "#" : "." %>
+<section>
+  <h1><a href="/?input=<%= @const_name %>"><%= CGI.escapeHTML(@const_name.to_s) %></a><%= method_type %><%= CGI.escapeHTML(@resp.dig(:attributes, :name).to_s) %></h1>
+</section>
+<section>
+  <h2>Arity: <%= attributes[:arity] %></h2>
+  <p>See <a target="_blank" href="https://ruby-doc.org/core-3.0.1/Method.html#method-i-arity">the official docs</a> for reference</p>
+</section>
+<% if attributes[:parameters].length.positive? %>
+  <section>
+    <h2>Parameters</h2>
+    <p>See <a href="https://ruby-doc.org/core-3.0.1/Method.html#method-i-parameters">the official docs</a> for reference</p>
+    <table>
+      <thead>
+        <tr><th>Name</th><th>Kind</th></tr>
+      </thead>
+      <tbody>
+        <% attributes[:parameters].each do |name, type| %>
+          <tr><td><%= name %></td><td><%= type %></td></tr>
+        <% end %>
+      </tbody>
+    </table>
+  </section>
+<% end %>
+<% if attributes[:defined_at] || attributes[:comment] || attributes[:source] %>
+  <section>
+    <% if attributes[:defined_at] %>
+      <% file, line_num = attributes[:defined_at].split(":") %>
+      <h2>Defined at</h2>
+      <p><a href="file://<%= file %>" target="_blank"><%= file %></a>, line number <%= line_num %></p>
+    <% end %>
+    <% if attributes[:comment] %>
+      <h2>Comment</h2>
+      <pre><code><%= attributes[:comment] %></code></pre>
+    <% end %>
+    <% if attributes[:source] %>
+      <h2>Source</h2>
+      <pre><code><%= attributes[:source] %></code></pre>
+    <% end %>
+  </section>
+<% end %>
+<% super_method = attributes.dig :super_method, :attributes %>
+<% if super_method %>
+  <section>
+    <h2>Super method</h2>
+    <p>
+      <a href="/?input=<%= CGI.escape(super_method[:belongs_to].name.to_s) %><%= CGI.escape(method_type) %><%= super_method[:name] %>">
+        <%= CGI.escapeHTML(super_method[:belongs_to].name.to_s) %> - <%= super_method[:name] %>
+      </a>
+    </p>
+  </section>
+<% end %>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qdocs
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Joseph Johansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-22 00:00:00.000000000 Z
+date: 2021-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: method_source
@@ -60,6 +60,10 @@ files:
 - lib/qdocs/active_record.rb
 - lib/qdocs/server.rb
 - lib/qdocs/version.rb
+- lib/views/common.html.erb
+- lib/views/constant/show.html.erb
+- lib/views/method/active_record_show.html.erb
+- lib/views/method/show.html.erb
 - qdocs.gemspec
 homepage:
 licenses: