ruby-lsp-rails-partial 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b2262132a35328b7bb8515a4cef737de185fc42aa2daf334685655721f9e1357
+  data.tar.gz: 6cef6d521642ca0e9a9e1b01343c6dd820c9c5eebab3b2297a40d7dd4fee961a
+SHA512:
+  metadata.gz: ec7ab69646adadc23d3d9eccc5768257d364994c8f5a542b06680f4dd7a344a39d3bf8b93ead06b05b5a1cb12fc3db05d998b64d6a673fbb47d049f82af93481
+  data.tar.gz: f0396414c88f72616c91926db9205051951492742c79c54bf25b883e656657cf7930c4d0bad3d6843d35fa7af8abf4a048e6aec089a77073e9237eacde23b8eb

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- Initial release.
+- Go to definition from a Rails `render` partial name string to the matching partial file.
+- Completion for partial names while typing inside the string.
+- Hover showing the list of resolved partial files as Markdown links.
+
+[Unreleased]: https://github.com/aki77/ruby-lsp-rails-partial/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/aki77/ruby-lsp-rails-partial/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 aki77
+
+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,45 @@
+# ruby-lsp-rails-partial
+
+[![CI](https://github.com/aki77/ruby-lsp-rails-partial/actions/workflows/ci.yml/badge.svg)](https://github.com/aki77/ruby-lsp-rails-partial/actions/workflows/ci.yml)
+
+A [Ruby LSP](https://github.com/Shopify/ruby-lsp) add-on that understands the partial name string
+of Rails `render` calls and provides:
+
+- **Go to definition** — jump from `render 'admin/areas/form'` (or `render partial: '...'`) to the
+  matching partial file. When multiple formats match, all candidates are offered.
+- **Completion** — complete partial names while typing inside the string. Partials in the same
+  directory are offered as bare names; others use the path form.
+- **Hover** — show the list of resolved partial files as Markdown links.
+
+Bare names (`render 'form'`) are resolved relative to the current view's directory, or to the
+controller name when called from a controller. Locale and variant qualifiers
+(`_form.en.html.erb`, `_form.html+phone.erb`) are treated as the same partial.
+
+## Installation
+
+Add the gem to your application's `Gemfile`:
+
+```ruby
+group :development do
+  gem 'ruby-lsp-rails-partial', require: false
+end
+```
+
+Then run `bundle install` and restart the Ruby LSP server in your editor. The add-on is discovered
+automatically by Ruby LSP via the `lib/ruby_lsp/**/addon.rb` convention.
+
+## Scope
+
+The view root is fixed to `app/views`. `prepend_view_path` / `append_view_path` and independent
+engines are not supported.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ruby_lsp/ruby_lsp_rails_partial/addon.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "version"
+require_relative "util"
+require_relative "partial_index"
+require_relative "partial_resolver"
+require_relative "definition"
+require_relative "completion"
+require_relative "hover"
+
+module RubyLsp
+  module RailsPartial
+    # Ruby LSP add-on that provides go-to-definition and completion for the partial name string of
+    # a render call.
+    #
+    # The view root is fixed to app/views (this add-on does not support prepend/append_view_path or
+    # independent engines).
+    class Addon < ::RubyLsp::Addon
+      WATCHER_REGISTRATION_ID = "rails-partial-watcher"
+
+      def activate(global_state, outgoing_queue)
+        views_path = File.join(global_state.workspace_path, "app", "views")
+        @index = PartialIndex.new(views_path)
+        @resolver = PartialResolver.new(@index, views_path)
+
+        register_file_watcher(global_state, outgoing_queue)
+      end
+
+      def deactivate; end
+
+      def name
+        "Rails Partial"
+      end
+
+      def version
+        VERSION
+      end
+
+      def create_definition_listener(response_builder, uri, node_context, dispatcher)
+        return unless @resolver
+
+        Definition.new(response_builder, uri, node_context, @resolver, dispatcher)
+      end
+
+      def create_completion_listener(response_builder, node_context, dispatcher, uri)
+        return unless @resolver
+
+        Completion.new(response_builder, node_context, @resolver, uri, dispatcher)
+      end
+
+      def create_hover_listener(response_builder, node_context, dispatcher)
+        return unless @resolver
+
+        Hover.new(response_builder, node_context, @resolver, dispatcher)
+      end
+
+      # Watches partial changes under app/views and updates the index incrementally.
+      def workspace_did_change_watched_files(changes)
+        return unless @index
+
+        changes.each do |change|
+          path = Util.uri_to_path(change[:uri])
+          next unless path
+
+          case change[:type]
+          when Constant::FileChangeType::CREATED, Constant::FileChangeType::CHANGED
+            @index.add(path)
+          when Constant::FileChangeType::DELETED
+            @index.remove(path)
+          end
+        end
+      end
+
+      private
+
+      def register_file_watcher(global_state, outgoing_queue)
+        return unless global_state.supports_watching_files
+
+        outgoing_queue << Request.register_watched_files(
+          1,
+          Interface::RelativePattern.new(
+            base_uri: global_state.workspace_uri.to_s,
+            pattern: "app/views/**/_*"
+          ),
+          registration_id: WATCHER_REGISTRATION_ID
+        )
+      end
+    end
+  end
+end

data/lib/ruby_lsp/ruby_lsp_rails_partial/completion.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RubyLsp
+  module RailsPartial
+    # Completes partial names while typing the partial name string of a render call.
+    # Candidates are always offered in path form (e.g. "admin/areas/form").
+    #
+    # NOTE: A completion request dispatches only the single node directly under the cursor, and the
+    # target node types do not include StringNode. When the cursor is inside the string, what gets
+    # dispatched is the enclosing CallNode (render), so this is handled in `on_call_node_enter`
+    # rather than `on_string_node_enter`.
+    class Completion
+      include Requests::Support::Common
+
+      # uri is part of the fixed listener signature but unused: candidates do not depend on the
+      # current file's directory (always path form).
+      def initialize(response_builder, node_context, resolver, _uri, dispatcher)
+        @response_builder = response_builder
+        @node_context = node_context
+        @resolver = resolver
+
+        dispatcher.register(self, :on_call_node_enter)
+      end
+
+      def on_call_node_enter(node)
+        return unless Util.render_call?(node)
+
+        string_node = Util.partial_string_argument(node)
+        return unless string_node
+
+        edit_range = content_range(string_node)
+        prefix = string_node.unescaped
+
+        @resolver.completion_candidates.each do |key, path|
+          # label, new_text, and the implicit filter_text (defaults to label) are all the path-form
+          # key, so the item survives the client-side filter regardless of how the user typed the
+          # reference. Mirrors ruby-lsp's require completion (build_completion).
+          next unless key.start_with?(prefix)
+
+          @response_builder << Interface::CompletionItem.new(
+            label: key,
+            kind: Constant::CompletionItemKind::FILE,
+            text_edit: Interface::TextEdit.new(range: edit_range, new_text: key),
+            detail: relative_detail(path)
+          )
+        end
+      end
+
+      private
+
+      # Range pointing at the inside of the string node's quotes. Falls back to the whole node if
+      # content_loc is absent.
+      def content_range(node)
+        location = node.content_loc || node.location
+        range_from_location(location)
+      end
+
+      def relative_detail(path)
+        return unless path
+
+        Util.relative_to_views(path)
+      end
+    end
+  end
+end

data/lib/ruby_lsp/ruby_lsp_rails_partial/definition.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RubyLsp
+  module RailsPartial
+    # When the cursor is on the partial name string of a render call, provides go-to-definition
+    # to the matching partial file. When multiple formats match, returns all Locations and lets
+    # ruby-lsp present the candidate picker.
+    class Definition
+      include Requests::Support::Common
+
+      def initialize(response_builder, uri, node_context, resolver, dispatcher)
+        @response_builder = response_builder
+        @uri = uri
+        @node_context = node_context
+        @resolver = resolver
+
+        dispatcher.register(self, :on_string_node_enter)
+      end
+
+      def on_string_node_enter(node)
+        return unless render_partial_argument?(node)
+
+        reference = node.unescaped
+        return if reference.empty?
+
+        # Highlight range of the origin. Pointing at the whole partial name (inside the quotes)
+        # makes the entire string a link even for names containing `/` like `admin/areas/form`.
+        origin_range = range_from_location(node.content_loc || node.location)
+
+        # The partial body is not parsed, so a leading zero-width range is reused as the target for
+        # all candidates. target_selection_range must be contained within target_range, so both are
+        # made identical.
+        target_range = Interface::Range.new(
+          start: Interface::Position.new(line: 0, character: 0),
+          end: Interface::Position.new(line: 0, character: 0)
+        )
+
+        @resolver.resolve(reference, @uri.to_s).each do |path|
+          @response_builder << Interface::LocationLink.new(
+            target_uri: URI::Generic.from_path(path:).to_s,
+            target_range:,
+            target_selection_range: target_range,
+            origin_selection_range: origin_range
+          )
+        end
+      end
+
+      private
+
+      # Whether this string node is the render call's partial argument (the first positional
+      # argument or the value of `partial:`). Decided by whether the StringNode under the cursor
+      # is identical to that render call's partial argument node.
+      def render_partial_argument?(node)
+        call_node = @node_context.call_node
+        return false unless call_node && Util.render_call?(call_node)
+
+        Util.partial_string_argument(call_node).equal?(node)
+      end
+    end
+  end
+end

data/lib/ruby_lsp/ruby_lsp_rails_partial/hover.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyLsp
+  module RailsPartial
+    # When the cursor is on the partial name string of a render call, shows the list of resolved
+    # file paths in a tooltip (Markdown).
+    #
+    # NOTE: A hover request does not pass a uri to the listener (unlike definition/completion).
+    # A bare name `render 'form'` needs a uri to infer the current directory, so it is out of
+    # scope; only slash-qualified names like `render 'admin/areas/form'` are resolved.
+    class Hover
+      def initialize(response_builder, node_context, resolver, dispatcher)
+        @response_builder = response_builder
+        @node_context = node_context
+        @resolver = resolver
+
+        dispatcher.register(self, :on_string_node_enter)
+      end
+
+      def on_string_node_enter(node)
+        return unless render_partial_argument?(node)
+
+        reference = node.unescaped
+        return if reference.empty?
+
+        paths = @resolver.resolve_without_context(reference)
+        return if paths.empty?
+
+        @response_builder.push("**Rails partial: `#{reference}`**", category: :title)
+        @response_builder.push(links_markdown(paths), category: :links)
+      end
+
+      private
+
+      # Renders each resolved file as a Markdown bullet link with its view-root-relative path.
+      def links_markdown(paths)
+        paths.sort.map { |path| link_line(path) }.join("\n")
+      end
+
+      def link_line(path)
+        uri = URI::Generic.from_path(path:).to_s
+        "- [#{Util.relative_to_views(path)}](#{uri})"
+      end
+
+      # Whether this string node is the render call's partial argument.
+      # This duplicates Definition's logic, but it is intentionally re-stated here so that the
+      # behavior can be followed within a single file (explicit duplication over implicit
+      # abstraction).
+      def render_partial_argument?(node)
+        call_node = @node_context.call_node
+        return false unless call_node && Util.render_call?(call_node)
+
+        Util.partial_string_argument(call_node).equal?(node)
+      end
+    end
+  end
+end

data/lib/ruby_lsp/ruby_lsp_rails_partial/partial_index.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module RubyLsp
+  module RailsPartial
+    # In-memory index of partials (`_*.*`) under the view root.
+    #
+    # ## Key normalization
+    # The path relative to the view root is normalized to "directory + basename without the
+    # leading underscore". All qualifiers that follow the partial name (format, handler, locale,
+    # variant) are dropped.
+    #   app/views/admin/areas/_form.html.erb        -> "admin/areas/form"
+    #   app/views/admin/areas/_form.en.html.erb     -> "admin/areas/form" (locale variant shares the key)
+    #   app/views/admin/areas/_form.html+phone.erb  -> "admin/areas/form" (variant shares the key)
+    # Since multiple formats can map to the same key, the value is always an array of file paths.
+    #
+    # The index is updated incrementally via file-watching events rather than re-globbing on every
+    # request (performance requirement).
+    class PartialIndex
+      def initialize(views_path)
+        @views_path = views_path
+        # normalized key => Array[absolute path]
+        @entries = Hash.new { |hash, key| hash[key] = [] }
+        build
+      end
+
+      # Returns the array of partial file paths for the normalized key, or an empty array if none.
+      def lookup(key)
+        @entries.fetch(key, [])
+      end
+
+      def all_entries
+        @entries
+      end
+
+      # Incremental update from a file-watching event. Paths that are not partials are ignored.
+      def add(absolute_path)
+        key = key_for(absolute_path)
+        return unless key
+
+        paths = @entries[key]
+        paths << absolute_path unless paths.include?(absolute_path)
+      end
+
+      def remove(absolute_path)
+        key = key_for(absolute_path)
+        return unless key
+
+        paths = @entries[key]
+        paths.delete(absolute_path)
+        @entries.delete(key) if paths.empty?
+      end
+
+      private
+
+      def build
+        Dir.glob(File.join(@views_path, "**", "_*.*")).each { |path| add(path) }
+      end
+
+      # Converts an absolute path to a normalized key. Returns nil unless it is a partial
+      # (basename starts with `_`).
+      def key_for(absolute_path)
+        relative = relative_from_views(absolute_path)
+        return unless relative
+
+        dir = File.dirname(relative)
+        basename = File.basename(relative)
+        return unless basename.start_with?("_")
+
+        # Strip the leading `_` and drop everything after the first `.`
+        # (format/handler/locale/variant).
+        name = basename[1..].split(".").first
+        return unless name
+
+        dir == "." ? name : "#{dir}/#{name}"
+      end
+
+      def relative_from_views(absolute_path)
+        prefix = "#{@views_path}/"
+        return unless absolute_path.start_with?(prefix)
+
+        absolute_path[prefix.length..]
+      end
+    end
+  end
+end

data/lib/ruby_lsp/ruby_lsp_rails_partial/partial_resolver.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RubyLsp
+  module RailsPartial
+    # Resolves the partial reference string of a `render` call to a PartialIndex key.
+    # Because resolution depends on the reference form and on the context of "which file the
+    # render is called from", this class is responsible only for bridging to the index's
+    # normalized key.
+    class PartialResolver
+      def initialize(index, views_path)
+        @index = index
+        @views_path = views_path
+      end
+
+      # Resolves a partial reference string ("foo" / "dir/foo") in the context of the current file
+      # and returns the array of absolute paths of the matching partial files.
+      def resolve(reference, current_uri)
+        key = key_for(reference, current_uri)
+        return [] unless key
+
+        @index.lookup(key)
+      end
+
+      # For contexts without a uri (hover). Only resolves references that contain a slash.
+      # Bare names are out of scope (they need a uri for directory inference) and return [].
+      def resolve_without_context(reference)
+        return [] unless reference.include?("/")
+
+        @index.lookup(reference)
+      end
+
+      # Returns completion candidates as an array of [key (path form), representative path].
+      # The key is always the normalized path form so that the display label, filter text, and
+      # inserted text all match, which keeps the item past the client-side filter regardless of
+      # how the user typed the reference.
+      def completion_candidates
+        @index.all_entries.map { |key, paths| [key, paths.first] }
+      end
+
+      private
+
+      # Converts a reference string to a normalized key.
+      # A slash means root-relative; otherwise it is relative to the current file's directory.
+      def key_for(reference, current_uri)
+        return if reference.empty?
+
+        if reference.include?("/")
+          reference
+        else
+          dir = current_dir(current_uri)
+          dir ? "#{dir}/#{reference}" : reference
+        end
+      end
+
+      # Derives the view-root-relative directory from the current file's URI.
+      # A view (under the view root) uses its own directory; a controller derives it from the
+      # controller name.
+      def current_dir(current_uri)
+        path = Util.uri_to_path(current_uri)
+        return unless path
+
+        if path.start_with?("#{@views_path}/")
+          relative = path[(@views_path.length + 1)..]
+          dir = File.dirname(relative)
+          dir == "." ? nil : dir
+        elsif path.include?("/app/controllers/")
+          controller_dir_from(path)
+        end
+      end
+
+      # Derives the view prefix from a controller file path.
+      #   app/controllers/admin/areas_controller.rb -> "admin/areas"
+      def controller_dir_from(path)
+        relative = path.split("/app/controllers/", 2).last
+        return unless relative
+
+        dir = relative.delete_suffix("_controller.rb")
+        dir.empty? ? nil : dir
+      end
+    end
+  end
+end

data/lib/ruby_lsp/ruby_lsp_rails_partial/util.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module RubyLsp
+  module RailsPartial
+    # AST inspection / path conversion helpers. Shared by the Definition / Completion / Hover
+    # listeners and by Addon / PartialResolver.
+    module Util
+      RENDER_METHODS = %i[render render_to_string].freeze
+      VIEWS_MARKER = "/app/views/"
+
+      class << self
+        # Converts a file:// URI to a filesystem path. Non-file:// URIs are returned as-is.
+        def uri_to_path(uri)
+          return uri unless uri.start_with?("file://")
+
+          URI.parse(uri).path
+        rescue URI::InvalidURIError
+          nil
+        end
+
+        # Returns the path relative to the app/views root. Falls back to the basename if the path
+        # is not under views.
+        def relative_to_views(path)
+          index = path.index(VIEWS_MARKER)
+          index ? path[(index + VIEWS_MARKER.length)..] : File.basename(path)
+        end
+
+        # Whether call_node is a render call with no receiver (or self).
+        def render_call?(call_node)
+          return false unless RENDER_METHODS.include?(call_node.message&.to_sym)
+
+          receiver = call_node.receiver
+          receiver.nil? || receiver.is_a?(Prism::SelfNode)
+        end
+
+        # Returns the string node of the render call's partial argument.
+        # The target is (1) the first positional argument, or (2) the value of the `partial:`
+        # keyword. Returns nil if neither is present.
+        def partial_string_argument(call_node)
+          arguments = call_node.arguments&.arguments
+          return unless arguments&.any?
+
+          first = arguments.first
+          return first if first.is_a?(Prism::StringNode)
+
+          partial_keyword_value(arguments)
+        end
+
+        private
+
+        # Returns the string node for the `partial:` keyword.
+        def partial_keyword_value(arguments)
+          keyword_hash = arguments.find { |arg| arg.is_a?(Prism::KeywordHashNode) }
+          return unless keyword_hash
+
+          assoc =
+            keyword_hash.elements.find do |element|
+              element.is_a?(Prism::AssocNode) &&
+                partial_key?(element.key) &&
+                element.value.is_a?(Prism::StringNode)
+            end
+          assoc&.value
+        end
+
+        def partial_key?(key)
+          key.is_a?(Prism::SymbolNode) && key.unescaped == "partial"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_lsp/ruby_lsp_rails_partial/version.rb

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

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: ruby-lsp-rails-partial
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- aki77
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby-lsp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.26.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.27.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.26.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.27.0
+description: Provides go-to-definition, completion, and hover for the partial name
+  string of Rails render calls.
+email:
+- 163168+aki77@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/ruby_lsp/ruby_lsp_rails_partial/addon.rb
+- lib/ruby_lsp/ruby_lsp_rails_partial/completion.rb
+- lib/ruby_lsp/ruby_lsp_rails_partial/definition.rb
+- lib/ruby_lsp/ruby_lsp_rails_partial/hover.rb
+- lib/ruby_lsp/ruby_lsp_rails_partial/partial_index.rb
+- lib/ruby_lsp/ruby_lsp_rails_partial/partial_resolver.rb
+- lib/ruby_lsp/ruby_lsp_rails_partial/util.rb
+- lib/ruby_lsp/ruby_lsp_rails_partial/version.rb
+homepage: https://github.com/aki77/ruby-lsp-rails-partial
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/aki77/ruby-lsp-rails-partial
+  changelog_uri: https://github.com/aki77/ruby-lsp-rails-partial/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Ruby LSP add-on for Rails partials
+test_files: []