ruby-lsp 0.4.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 437c2048862bed450fd70057489636117c99943dd7bb68df35c4e161a29f8385
-  data.tar.gz: 30d26e8455f9086bc934ffe23b5e37816f18f5904e3422495c316a980a860cfc
+  metadata.gz: f8f2f2aa1083dcc700e709ebd0bc3d3aed8f08d80943595ba3c9df332d806709
+  data.tar.gz: a065d2f6be6539c81ad117bfba7c7b4f90ead0bbce37dd936733218e3135bc67
 SHA512:
-  metadata.gz: 366dd4b756ded58762b598545e398059fe0eae7578b13c92cc0a90dcc9aba2d58106dbf2dc0e9867a9db7de5007e6114ebbbf7cf191bcdebb843b077de945ba9
-  data.tar.gz: 1f798c1462825cccafd48bff23baecb8ba8ef36f9b5733502d79c5d8e6e52550c7ab722a99678eec04ce2a8b42c4d84aab912acb2100ff7d26e422b02f2c185b
+  metadata.gz: de010f852e08fd72ac60a12cbb9a8666a92945c49b8a14214f0e347c9a6fbacb65770322627db22a30b573ee61f34ec18be56d625768a6c954cf447dbda63368
+  data.tar.gz: 3f47e62896899091c4a9b166937720cc535f46004827a098bfb7eaf9c31fb39bb35261077b91a01a41baa18a50482d8ffe1b8ebddabaed1ea15bc0d023e76dae

data/README.md

@@ -2,7 +2,6 @@
 [![Ruby LSP extension](https://img.shields.io/badge/VS%20Code-Ruby%20LSP-success?logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=Shopify.ruby-lsp)
 [![Ruby DX Slack](https://img.shields.io/badge/Slack-Ruby%20DX-success?logo=slack)](https://join.slack.com/t/ruby-dx/shared_invite/zt-1s6f4y15t-v9jedZ9YUPQLM91TEJ4Gew)
 
-
 # Ruby LSP
 
 The Ruby LSP is an implementation of the [language server protocol](https://microsoft.github.io/language-server-protocol/)
@@ -21,8 +20,7 @@ get the extra features in the editor. Do not install this gem manually.
 
 ### With other editors
 
-See [editors](https://github.com/Shopify/ruby-lsp/blob/main/EDITORS.md) for community instructions on setting up the
-Ruby LSP.
+See [editors](EDITORS.md) for community instructions on setting up the Ruby LSP.
 
 The gem can be installed by doing
 ```shell
@@ -51,92 +49,13 @@ See the [documentation](https://shopify.github.io/ruby-lsp) for more in-depth de
 Bug reports and pull requests are welcome on GitHub at https://github.com/Shopify/ruby-lsp.
 This project is intended to be a safe, welcoming space for collaboration, and contributors
 are expected to adhere to the
-[Contributor Covenant](https://github.com/Shopify/ruby-lsp/blob/main/CODE_OF_CONDUCT.md)
+[Contributor Covenant](CODE_OF_CONDUCT.md)
 code of conduct.
 
-### Running the test suite
-
-Run the test suite with `bin/test`.
-
-For more visibility into which tests are running, use the `SpecReporter`:
-
-`SPEC_REPORTER=1 bin/test`
-
-By default the tests run with warnings disabled to reduce noise. To enable warnings, pass `VERBOSE=1`.
-Warnings are always shown when running in CI.
-
-### Expectation testing
-
-To simplify the way we run tests over different pieces of Ruby code, we use a custom expectations test framework against a set of Ruby fixtures.
-
-We define expectations as `.exp` files, of which there are two variants:
-* `.exp.rb`, to indicate the resulting code after an operation.
-* `.exp.json`, consisting of a `result`, and an optional set of input `params`.
-
-To add a new fixture to the expectations test suite:
-
-1. Add a new fixture `my_fixture.rb` file under `test/fixtures`
-2. (optional) Add new expectations under `test/expectations/$HANDLER` for the request handlers you're concerned by
-3. Profit by running `bin/test test/requests/$HANDLER_expectations_test my_fixture`
-    * Handlers for which you added expectations will be checked with `assert_expectations`
-    * Handlers without expectations will be ran against your new test to check that nothing breaks
-
-To add a new expectations test runner for a new request handler:
-
-1. Add a new file under `test/requests/$HANDLER_expectations_test.rb` that subclasses `ExpectationsTestRunner` and calls `expectations_tests $HANDLER, "$EXPECTATIONS_DIR"` where: `$HANDLER` is the fully qualified name or your handler class and `$EXPECTATIONS_DIR` is the directory name where you want to store the expectation files.
-
-   ```rb
-   # frozen_string_literal: true
-
-   require "test_helper"
-   require "expectations/expectations_test_runner"
-
-   class $HANDLERExpectationsTest < ExpectationsTestRunner
-     expectations_tests RubyLsp::Requests::$HANDLER, "$EXPECTATIONS_DIR"
-   end
-   ```
-
-2. (optional) Override the `run_expectations` and `assert_expectations` methods if needed. See the different request handler expectations runners under `test/requests/*_expectations_test.rb` for examples.
-
-4. (optional) Add new fixtures for your handler under `test/fixtures`
-
-5. (optional) Add new expectations under `test/expectations/$HANDLER`
-   * No need to write the expectations by hand, just run the test with an empty expectation file and copy from the output.
-
-7. Profit by running, `bin/test test/expectations_test $HANDLER`
-    * Tests with expectations will be checked with `assert_expectations`
-    * Tests without expectations will be ran against your new $HANDLER to check that nothing breaks
-
-### Debugging
-
-### Debugging Tests
-
-1. Open the test file.
-2. Set a breakpoint(s) on lines by clicking next to their numbers.
-3. Open VS Code's `Run and Debug` panel.
-4. At the top of the panel, select `Minitset - current file` and click the green triangle (or press F5).
-
-### Debugging Running Ruby LSP Process
-
-1. Open the `vscode-ruby-lsp` project in VS Code.
-2. [`vscode-ruby-lsp`] Open VS Code's `Run and Debug` panel.
-3. [`vscode-ruby-lsp`] Select `Run Extension` and click the green triangle (or press F5).
-4. [`vscode-ruby-lsp`] Now VS Code will:
-    - Open another workspace as the `Extension Development Host`.
-    - Run `vscode-ruby-lsp` extension in debug mode, which will start a new `ruby-lsp` process with the `--debug` flag. Note that debugging is not available on Windows.
-5. Open `ruby-lsp` in VS Code.
-6. [`ruby-lsp`] Run `bin/rdbg -A` to connect to the running `ruby-lsp` process.
-7. [`ruby-lsp`] Use commands like `b <file>:<line>` or `b Class#method` to set breakpoints and type `c` to continue the process.
-8. In your `Extension Development Host` project (e.g. [`Tapioca`](https://github.com/Shopify/tapioca)), trigger the request that will hit the breakpoint.
-
-### Spell Checking
-
-VS Code users will be prompted to enable the [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) extension.
-By default this will be enabled for all workspaces, but you can choose to selectively enable or disable it per workspace.
-
-If you introduce a word which the spell checker does not recognize, you can add it to the `cspell.json` configuration alongside your PR.
+If you wish to contribute, see [CONTRIBUTING](CONTRIBUTING.md) for development instructions and check out our pinned
+[roadmap issue](https://github.com/Shopify/ruby-lsp/issues) for a list of tasks to get started.
 
 ## License
 
 The gem is available as open source under the terms of the
-[MIT License](https://github.com/Shopify/ruby-lsp/blob/main/LICENSE.txt).
+[MIT License](LICENSE.txt).

data/VERSION

@@ -1 +1 @@
-0.4.5
+0.5.0

data/lib/ruby_lsp/check_docs.rb

@@ -0,0 +1,112 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "ruby_lsp/internal"
+require "objspace"
+
+module RubyLsp
+  # This rake task checks that all requests or extensions are fully documented. Add the rake task to your Rakefile and
+  # specify the absolute path for all files that must be required in order to discover all listeners
+  #
+  #   # Rakefile
+  #   request_files = FileList.new("#{__dir__}/lib/ruby_lsp/requests/*.rb") do |fl|
+  #     fl.exclude(/base_request\.rb/)
+  #   end
+  #   RubyLsp::CheckDocs.new(request_files)
+  #   # Run with bundle exec rake ruby_lsp:check_docs
+  class CheckDocs < Rake::TaskLib
+    extend T::Sig
+
+    sig { params(require_files: Rake::FileList).void }
+    def initialize(require_files)
+      super()
+
+      @name = T.let("ruby_lsp:check_docs", String)
+      @file_list = require_files
+      define_task
+    end
+
+    private
+
+    sig { void }
+    def define_task
+      desc("Checks if all Ruby LSP listeners are documented")
+      task(@name) { run_task }
+    end
+
+    sig { void }
+    def run_task
+      # Require all files configured to make sure all listeners are loaded
+      @file_list.each { |f| require(f.delete_suffix(".rb")) }
+
+      # Find all classes that inherit from BaseRequest or Listener, which are the ones we want to make sure are
+      # documented
+      features = ObjectSpace.each_object(Class).filter_map do |k|
+        klass = T.cast(k, Class)
+        klass if klass < RubyLsp::Requests::BaseRequest || klass < RubyLsp::Listener
+      end
+
+      missing_docs = T.let(Hash.new { |h, k| h[k] = [] }, T::Hash[String, T::Array[String]])
+
+      features.each do |klass|
+        class_name = T.must(klass.name)
+        file_path, line_number = Module.const_source_location(class_name)
+        next unless file_path && line_number
+
+        # Adjust the line number to start searching right above the class definition
+        line_number -= 2
+
+        lines = File.readlines(file_path)
+        docs = []
+
+        # Extract the documentation on top of the listener constant
+        while (line = lines[line_number]&.strip) && line.start_with?("#")
+          docs.unshift(line)
+          line_number -= 1
+        end
+
+        documentation = docs.join("\n")
+
+        if docs.empty?
+          T.must(missing_docs[class_name]) << "No documentation found"
+        elsif !%r{\(https://microsoft.github.io/language-server-protocol/specification#.*\)}.match?(documentation)
+          T.must(missing_docs[class_name]) << <<~DOCS
+            Missing specification link. Requests and extensions should include a link to the LSP specification for the
+            related feature. For example:
+
+            [Inlay hint](https://microsoft.github.io/language-server-protocol/specification#textDocument_inlayHint)
+          DOCS
+        elsif !documentation.include?("# Example")
+          T.must(missing_docs[class_name]) << <<~DOCS
+            Missing example. Requests and extensions should include a code example that explains what the feature does.
+
+            # # Example
+            # ```ruby
+            # class Foo # <- information is shown here
+            # end
+            # ```
+          DOCS
+        elsif !/\[.* demo\]\(.*\.gif\)/.match?(documentation)
+          T.must(missing_docs[class_name]) << <<~DOCS
+            Missing demonstration GIF. Each request and extension must be documented with a GIF that shows the feature
+            working. For example:
+
+            # [Inlay hint demo](../../inlay_hint.gif)
+          DOCS
+        end
+      end
+
+      if missing_docs.any?
+        warn(<<~WARN)
+          The following listeners are missing documentation:
+
+          #{missing_docs.map { |k, v| "#{k}\n\n#{v.join("\n")}" }.join("\n\n")}
+        WARN
+
+        abort
+      end
+
+      puts "All listeners are documented!"
+    end
+  end
+end

data/lib/ruby_lsp/document.rb

@@ -23,7 +23,7 @@ module RubyLsp
 
     sig { params(source: String, version: Integer, uri: String, encoding: String).void }
     def initialize(source:, version:, uri:, encoding: Constant::PositionEncodingKind::UTF8)
-      @cache = T.let({}, T::Hash[Symbol, T.untyped])
+      @cache = T.let({}, T::Hash[String, T.untyped])
       @encoding = T.let(encoding, String)
       @source = T.let(source, String)
       @version = T.let(version, Integer)
@@ -40,10 +40,11 @@ module RubyLsp
       @source == other.source
     end
 
+    # TODO: remove this method once all nonpositional requests have been migrated to the listener pattern
     sig do
       type_parameters(:T)
         .params(
-          request_name: Symbol,
+          request_name: String,
           block: T.proc.params(document: Document).returns(T.type_parameter(:T)),
         ).returns(T.type_parameter(:T))
     end
@@ -56,6 +57,16 @@ module RubyLsp
       result
     end
 
+    sig { type_parameters(:T).params(request_name: String, value: T.type_parameter(:T)).returns(T.type_parameter(:T)) }
+    def cache_set(request_name, value)
+      @cache[request_name] = value
+    end
+
+    sig { params(request_name: String).returns(T.untyped) }
+    def cache_get(request_name)
+      @cache[request_name]
+    end
+
     sig { params(edits: T::Array[EditShape], version: Integer).void }
     def push_edits(edits, version:)
       edits.each do |edit|

data/lib/ruby_lsp/event_emitter.rb

@@ -13,42 +13,108 @@ module RubyLsp
   #
   # ```ruby
   # target_node = document.locate_node(position)
-  # listener = Requests::Hover.new
-  # EventEmitter.new(listener).emit_for_target(target_node)
+  # emitter = EventEmitter.new
+  # listener = Requests::Hover.new(emitter, @message_queue)
+  # emitter.emit_for_target(target_node)
   # listener.response
   # ```
   class EventEmitter < SyntaxTree::Visitor
     extend T::Sig
 
-    sig { params(listeners: Listener[T.untyped]).void }
-    def initialize(*listeners)
-      @listeners = listeners
-
-      # Create a map of event name to listeners that have registered it, so that we avoid unnecessary invocations
-      @event_to_listener_map = T.let(
-        listeners.each_with_object(Hash.new { |h, k| h[k] = [] }) do |listener, hash|
-          listener.class.events&.each { |event| hash[event] << listener }
-        end,
-        T::Hash[Symbol, T::Array[Listener[T.untyped]]],
-      )
-
+    sig { void }
+    def initialize
+      @listeners = T.let(Hash.new { |h, k| h[k] = [] }, T::Hash[Symbol, T::Array[Listener[T.untyped]]])
       super()
     end
 
+    sig { params(listener: Listener[T.untyped], events: Symbol).void }
+    def register(listener, *events)
+      events.each { |event| T.must(@listeners[event]) << listener }
+    end
+
     # Emit events for a specific node. This is similar to the regular `visit` method, but avoids going deeper into the
     # tree for performance
     sig { params(node: T.nilable(SyntaxTree::Node)).void }
     def emit_for_target(node)
       case node
       when SyntaxTree::Command
-        @event_to_listener_map[:on_command]&.each { |listener| T.unsafe(listener).on_command(node) }
+        @listeners[:on_command]&.each { |l| T.unsafe(l).on_command(node) }
       when SyntaxTree::CallNode
-        @event_to_listener_map[:on_call]&.each { |listener| T.unsafe(listener).on_call(node) }
+        @listeners[:on_call]&.each { |l| T.unsafe(l).on_call(node) }
+      when SyntaxTree::TStringContent
+        @listeners[:on_tstring_content]&.each { |l| T.unsafe(l).on_tstring_content(node) }
       when SyntaxTree::ConstPathRef
-        @event_to_listener_map[:on_const_path_ref]&.each { |listener| T.unsafe(listener).on_const_path_ref(node) }
+        @listeners[:on_const_path_ref]&.each { |l| T.unsafe(l).on_const_path_ref(node) }
       when SyntaxTree::Const
-        @event_to_listener_map[:on_const]&.each { |listener| T.unsafe(listener).on_const(node) }
+        @listeners[:on_const]&.each { |l| T.unsafe(l).on_const(node) }
       end
     end
+
+    # Visit dispatchers are below. Notice that for nodes that create a new scope (e.g.: classes, modules, method defs)
+    # we need both an `on_*` and `after_*` event. This is because some requests must know when we exit the scope
+    sig { override.params(node: SyntaxTree::ClassDeclaration).void }
+    def visit_class(node)
+      @listeners[:on_class]&.each { |l| T.unsafe(l).on_class(node) }
+      super
+      @listeners[:after_class]&.each { |l| T.unsafe(l).after_class(node) }
+    end
+
+    sig { override.params(node: SyntaxTree::ModuleDeclaration).void }
+    def visit_module(node)
+      @listeners[:on_module]&.each { |l| T.unsafe(l).on_module(node) }
+      super
+      @listeners[:after_module]&.each { |l| T.unsafe(l).after_module(node) }
+    end
+
+    sig { override.params(node: SyntaxTree::Command).void }
+    def visit_command(node)
+      @listeners[:on_command]&.each { |l| T.unsafe(l).on_command(node) }
+      super
+      @listeners[:after_command]&.each { |l| T.unsafe(l).after_command(node) }
+    end
+
+    sig { override.params(node: SyntaxTree::CallNode).void }
+    def visit_call(node)
+      @listeners[:on_call]&.each { |l| T.unsafe(l).on_call(node) }
+      super
+      @listeners[:after_call]&.each { |l| T.unsafe(l).after_call(node) }
+    end
+
+    sig { override.params(node: SyntaxTree::VCall).void }
+    def visit_vcall(node)
+      @listeners[:on_vcall]&.each { |l| T.unsafe(l).on_vcall(node) }
+      super
+    end
+
+    sig { override.params(node: SyntaxTree::ConstPathField).void }
+    def visit_const_path_field(node)
+      @listeners[:on_const_path_field]&.each { |l| T.unsafe(l).on_const_path_field(node) }
+      super
+    end
+
+    sig { override.params(node: SyntaxTree::TopConstField).void }
+    def visit_top_const_field(node)
+      @listeners[:on_top_const_field]&.each { |l| T.unsafe(l).on_top_const_field(node) }
+      super
+    end
+
+    sig { override.params(node: SyntaxTree::DefNode).void }
+    def visit_def(node)
+      @listeners[:on_def]&.each { |l| T.unsafe(l).on_def(node) }
+      super
+      @listeners[:after_def]&.each { |l| T.unsafe(l).after_def(node) }
+    end
+
+    sig { override.params(node: SyntaxTree::VarField).void }
+    def visit_var_field(node)
+      @listeners[:on_var_field]&.each { |l| T.unsafe(l).on_var_field(node) }
+      super
+    end
+
+    sig { override.params(node: SyntaxTree::Comment).void }
+    def visit_comment(node)
+      @listeners[:on_comment]&.each { |l| T.unsafe(l).on_comment(node) }
+      super
+    end
   end
 end