ruby-lsp-doclinks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 12954ad2e802bc2f08441ab59082fb0a89a119292351e87a8d14efd9c3df7e69
+  data.tar.gz: 809235b97945b4b34cc09871d9d2a19316c70a649c3f1555389089ebf003aca5
+SHA512:
+  metadata.gz: 8fb13af91f8b99ce58cf4f01de07c28614a7ce9008491e7bacdf7401afe3822192e780b4e0691bbed7dda3e14e87804741eb56584f33ac3d93cf3b66ef3a3068
+  data.tar.gz: a79bed4dc2aa720abcca1cf5f155f5db6f105c37701c8d47d7330a187cee78361d7b0526ae0a05f876fb7bc2903fdcc389a2f3d258fbb5df1bdb72971bcde400

data/.rubocop.yml

@@ -0,0 +1,2 @@
+# Omakase Ruby styling for Rails
+inherit_gem: { rubocop-rails-omakase: rubocop.yml }

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+=## [0.1.0] - 2025-03-25
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Matt Conway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,67 @@
+# Ruby::Lsp::Doclinks
+
+An addon for the VsCode RubyLsp extension that provides documentation links in hovers for constants (classes/modules), and their methods
+
+## Installation
+
+Setup VsCode to use the [Ruby-LSP extension](https://marketplace.visualstudio.com/items?itemName=Shopify.ruby-lsp), then install this gem so that Ruby-LSP can find it.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add ruby-lsp-doclinks
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install ruby-lsp-doclinks
+```
+
+## Usage
+
+By default, the addon will use rubygems as it's documentation source.  If you hover over a constant, like a classname, it will generate a link to documentation at the bottom of the hover.
+
+If you'd like to use a yard server or something custom, you can customize the documentation url through the Ruby LSP addon settings in settings.json which will look something like:
+```json
+    "rubyLsp.addonSettings": {
+        "Doclinks": {
+            // Source can be anything so long as you have a matching "<source>_url" setting
+            // Urls for yard and rubydoc are predefined as shown below
+            //
+            "doc_source": "yard"
+
+            // Optionally customize the url pattern, default formats are
+            //
+            // "yard_url": "http://localhost:8808/docs/%{gem_name}/%{version}/%{constant}#%{method}"
+            // "rubydoc_url": "https://www.rubydoc.info/gems/%{gem_name}/%{version}/%{constant}#%{method}"
+            // "custom_url": "Add a custom Url for %{gem_name} %{version} %{constant} %{method}"
+        }
+    }
+```
+
+
+## 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.
+
+You can point your project to a path based version of the gem with an entry in your Gemfile like:
+```
+  gem "ruby-lsp-doclinks", path: "~/myprojects/ruby-lsp-doclinks"
+```
+
+Make sure to `Cmd-Shift-P` - `Developer: Reload Window` in VsCode to reload LSP and this plugin in order to see the result of any code changes.  Select the `Ruby LSP` from the dorpdown in the VsCode `Output` panel to see any logs.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/wr0ngway/ruby-lsp-doclinks. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/wr0ngway/ruby-lsp-doclinks/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Ruby::Lsp::Doclinks project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/wr0ngway/ruby-lsp-doclinks/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/ruby-lsp-doclinks.rb

@@ -0,0 +1 @@
+require "ruby_lsp/doclinks/version"

data/lib/ruby_lsp/doclinks/addon.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "ruby_lsp/addon"
+require "ruby_lsp/requests/support/common"
+
+module RubyLsp
+  module DocLinks
+    class Addon < ::RubyLsp::Addon
+      def initialize
+        super
+
+        @settings = {
+          rubydoc_url: "https://www.rubydoc.info/gems/%{gem_name}/%{version}/%{constant}#%{method}",
+          yard_url: "http://localhost:8808/docs/%{gem_name}/%{version}/%{constant}#%{method}",
+          custom_url: "Add a custom Url for %{gem_name} %{version} %{constant} %{method}",
+          doc_source: :rubydoc # :rubydoc, :yard or :custom
+        }
+      end
+
+      def activate(global_state, message_queue)
+        @global_state = global_state
+        @message_queue = message_queue
+        $stderr.puts "Activating '#{name}' LSP addon v#{RubyLsp::Doclinks::VERSION}"
+
+        addon_settings = @global_state.settings_for_addon(name)
+        $stderr.puts "#{name} addon settings: #{addon_settings.inspect}"
+        @settings.merge!(addon_settings) if addon_settings
+      end
+
+      def deactivate
+        # No cleanup needed
+      end
+
+      def name
+        "Doclinks"
+      end
+
+      def version
+        "0.1.0"
+      end
+
+      def create_hover_listener(response_builder, node_context, dispatcher)
+        Hover.new(@settings, response_builder, dispatcher)
+      end
+    end
+
+    class Hover
+      include Requests::Support::Common
+
+      def initialize(settings, response_builder, dispatcher)
+        @settings = settings
+        @response_builder = response_builder
+
+
+        # Subscribe to various node types
+        dispatcher.register(self, :on_constant_read_node_enter)
+        dispatcher.register(self, :on_constant_path_node_enter)
+        dispatcher.register(self, :on_call_node_enter)
+      end
+
+      def on_constant_read_node_enter(node)
+        # $stderr.puts "#{name} addon handling on_constant_read_node_enter: #{node.inspect} slice=#{node&.slice&.inspect}"
+        constant = node.slice
+        handle_constant(constant)
+      end
+
+      def on_constant_path_node_enter(node)
+        # $stderr.puts "#{name} addon handling on_constant_path_node_enter: #{node.inspect} slice=#{node&.slice&.inspect}"
+        # Handle nested constants like Foo::Bar
+        constant = node.slice
+        handle_constant(constant)
+      end
+
+      def on_call_node_enter(node)
+        # $stderr.puts "#{name} addon handling on_call_node_enter: #{node.name} receiver_slice=#{node&.receiver&.slice&.inspect}"
+        # Handle method calls
+        constant = node.receiver&.slice
+        method = node.name
+        # $stderr.puts "#{name} addon constant=#{constant} method=#{method} node=#{node.inspect}"
+        handle_constant(constant, method)
+      end
+
+      private
+
+      def handle_constant(constant, method_name = nil)
+        # $stderr.puts "#{name} addon handling: #{constant}#{method_name ? "##{method_name}" : ""}"
+        return unless constant && !constant.empty?
+
+        # Check if the word is a gem constant
+        gem_info = find_gem_for_constant(constant)
+        # $stderr.puts "#{name} addon gem_info: #{gem_info.inspect}"
+        return unless gem_info
+
+        # Generate documentation link based on configuration
+        doc_link = generate_doc_link(gem_info, constant, method_name)
+        # $stderr.puts "#{name} addon doc_link: #{doc_link}"
+        return unless doc_link
+
+        # $stderr.puts "#{name} addon adding hover response"
+        display_name = method_name ? "#{constant}##{method_name}" : constant
+        content = "\n[View documentation for #{display_name}](#{doc_link})"
+        @response_builder.push(content, category: :documentation)
+      end
+
+      def find_gem_for_constant(constant)
+        # Try with the full constant path first
+        gem_info = find_gem_with_constant(constant)
+        return gem_info if gem_info
+
+        # If not found, try with the base constant
+        base_constant = constant.split("::").first
+        return nil if base_constant.nil? || base_constant.empty?
+
+        find_gem_with_constant(base_constant)
+      end
+
+      def find_gem_with_constant(constant_name)
+        Gem.loaded_specs.find do |name, spec|
+          spec.full_require_paths.any? do |path|
+            next if path.nil? || path.empty?
+
+            Dir.glob("#{path}/**/*.rb").any? do |file|
+              next if file.nil?
+
+              begin
+                content = File.read(file)
+                next if content.nil? || content.empty?
+
+                # Look for class/module definitions with the exact constant name
+                content.match?(/\b(?:class|module)\s+#{Regexp.escape(constant_name)}\b/)
+              rescue => e
+                $stderr.puts "Error reading file #{file}: #{e.message}"
+                false
+              end
+            end
+          end
+        end
+      end
+
+      def generate_doc_link(gem_info, constant, method_name = nil)
+        return nil if gem_info.nil? || constant.nil? || constant.empty?
+
+        name, spec = gem_info
+        return nil if name.nil? || spec.nil?
+
+        source = @settings[:doc_source]
+        base_url = @settings["#{source}_url".to_sym]
+        return nil if base_url.nil?
+
+        # TODO: figure out to get more than a constant's class method.
+        # e.g. an instance method on a local variable
+        method_type = method_name ? "-class_method" : ""
+        doc_url = base_url % {
+          gem_name: name,
+          version: spec.version,
+          constant: constant.gsub("::", "/"),
+          method: "#{method_name}#{method_type}"
+        }
+        $stderr.puts "#{name} addon doc_url for source=#{source}: #{doc_url}"
+
+        doc_url
+      end
+    end
+  end
+end

data/lib/ruby_lsp/doclinks/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLsp
+  module Doclinks
+    VERSION = "0.1.0"
+  end
+end

data/lib/ruby_lsp/doclinks.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "doclinks/version"
+
+module RubyLsp
+  module Doclinks
+    class Error < StandardError; end
+  end
+end

data/sig/ruby_lsp/doclinks.rbs

@@ -0,0 +1,4 @@
+module RubyLsp::Doclinks
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/sorbet/config

@@ -0,0 +1,4 @@
+--dir
+.
+--ignore=tmp/
+--ignore=vendor/

data/sorbet/rbi/annotations/.gitattributes

@@ -0,0 +1 @@
+**/*.rbi linguist-vendored=true