rubydex 0.2.9 → 0.4.0

data/lib/ruby_lsp/rubydex/addon.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "rubydex/linter"
+
+# This add-on is only supported by the beta version of the LSP. We don't want to keep showing window dialogs to users of
+# the stable version until the v0.27 series is stable, so here we are hand-rolling our own `depend_on_ruby_lsp!` method
+# to avoid notifying them.
+lsp_version = Gem::Version.new(RubyLsp::VERSION)
+return unless [">= 0.27.0.beta4", "< 0.28"].all? { |constraint| Gem::Requirement.new(constraint).satisfied_by?(lsp_version) }
+
+module Rubydex
+  module Linter
+    module RubyLsp
+      class Addon < ::RubyLsp::Addon
+        CONFIGURATION_FILE = "rubydex.toml" #: String
+
+        # @override
+        #: () -> String
+        def name
+          "Rubydex Linter"
+        end
+
+        # @override
+        #: () -> String
+        def version
+          ::Rubydex::VERSION
+        end
+
+        # @override
+        #: (::RubyLsp::GlobalState, Thread::Queue) -> void
+        def activate(global_state, outgoing_queue)
+          @outgoing_queue = outgoing_queue #: Thread::Queue?
+          @linter = Linter.new(global_state) #: Linter?
+
+          global_state.register_formatter(
+            "rubydex",
+            @linter, #: as !nil
+          )
+
+          register_additional_file_watchers(global_state, outgoing_queue)
+        end
+
+        # @override
+        #: () -> void
+        def deactivate; end
+
+        #: (Array[{ uri: String, type: Integer }]) -> void
+        def workspace_did_change_watched_files(changes)
+          return unless @linter && @outgoing_queue
+
+          @linter.reload_configuration if changes.any? { |change| configuration_change?(change) }
+          @linter.lint!
+
+          @linter.diagnostics_to_clear.each do |uri|
+            @outgoing_queue << ::RubyLsp::Notification.publish_diagnostics(uri, [])
+          end
+
+          @linter.current_diagnostics.each do |uri, diagnostics|
+            @outgoing_queue << ::RubyLsp::Notification.publish_diagnostics(uri, diagnostics)
+          end
+        end
+
+        private
+
+        #: (::RubyLsp::GlobalState, Thread::Queue) -> void
+        def register_additional_file_watchers(global_state, outgoing_queue)
+          return unless global_state.client_capabilities.supports_watching_files
+
+          outgoing_queue << ::RubyLsp::Request.new(
+            id: "rubydex-linter-file-watcher",
+            method: "client/registerCapability",
+            params: ::RubyLsp::Interface::RegistrationParams.new(
+              registrations: [
+                ::RubyLsp::Interface::Registration.new(
+                  id: "workspace/didChangeWatchedFilesRubydexLinter",
+                  method: "workspace/didChangeWatchedFiles",
+                  register_options: ::RubyLsp::Interface::DidChangeWatchedFilesRegistrationOptions.new(
+                    watchers: [
+                      ::RubyLsp::Interface::FileSystemWatcher.new(
+                        glob_pattern: ::RubyLsp::Interface::RelativePattern.new(
+                          base_uri: global_state.workspace_uri.to_s,
+                          pattern: CONFIGURATION_FILE,
+                        ),
+                        kind: ::RubyLsp::Constant::WatchKind::CREATE | ::RubyLsp::Constant::WatchKind::CHANGE,
+                      ),
+                    ],
+                  ),
+                ),
+              ],
+            ),
+          )
+        end
+
+        # The Ruby LSP forwards every watched file change to every add-on, including the ones registered by other add-ons,
+        # so we have to check that the change is actually about our configuration file.
+        #: ({ uri: String, type: Integer }) -> bool
+        def configuration_change?(change)
+          path = URI(change[:uri]).full_path
+          return false unless path
+
+          File.basename(path) == CONFIGURATION_FILE
+        end
+      end
+
+      class Linter
+        include ::RubyLsp::Requests::Support::Formatter
+
+        DIAGNOSTIC_SEVERITIES = {
+          ::Rubydex::Severity::Error => ::RubyLsp::Constant::DiagnosticSeverity::ERROR,
+          ::Rubydex::Severity::Warning => ::RubyLsp::Constant::DiagnosticSeverity::WARNING,
+          ::Rubydex::Severity::Information => ::RubyLsp::Constant::DiagnosticSeverity::INFORMATION,
+          ::Rubydex::Severity::Hint => ::RubyLsp::Constant::DiagnosticSeverity::HINT,
+        }.freeze #: Hash[singleton(::Rubydex::Severity::Base), Integer]
+
+        #: Hash[String, Array[::RubyLsp::Interface::Diagnostic]]
+        attr_reader :current_diagnostics
+
+        #: Array[String]
+        attr_reader :diagnostics_to_clear
+
+        #: (::RubyLsp::GlobalState) -> void
+        def initialize(global_state)
+          @graph = global_state.graph #: ::Rubydex::Graph
+          @workspace_path = global_state.workspace_path #: String
+          ::Rubydex::Linter::RuleLoader.load(@workspace_path)
+          @custom_rules = ::Rubydex::Linter::CustomRule.subclasses #: Array[singleton(::Rubydex::Linter::CustomRule)]
+
+          @config = ::Rubydex::Config.load(@workspace_path) #: ::Rubydex::Config
+          @runner = ::Rubydex::Linter::Runner.new(@graph, custom_rules: @custom_rules, config: @config.linter) #: ::Rubydex::Linter::Runner
+
+          @current_diagnostics = {} #: Hash[String, Array[::RubyLsp::Interface::Diagnostic]]
+          @diagnostics_to_clear = [] #: Array[String]
+        end
+
+        # @override
+        #: (URI::Generic, ::RubyLsp::Document[untyped]) -> Array[::RubyLsp::Interface::Diagnostic]?
+        def run_diagnostic(uri, _document)
+          @current_diagnostics[uri.to_s]
+        end
+
+        # @override
+        #: (URI::Generic, ::RubyLsp::RubyDocument) -> String?
+        def run_formatting(uri, document); end
+
+        # @override
+        #: (URI::Generic, String, Integer) -> String?
+        def run_range_formatting(uri, source, base_indentation); end
+
+        #: () -> void
+        def lint!
+          @diagnostics_to_clear = @current_diagnostics.keys
+          @current_diagnostics.clear
+
+          linter_config = @config.linter
+
+          @runner.run.each do |diagnostic|
+            uri = diagnostic.location.uri
+            (@current_diagnostics[uri] ||= []) << to_lsp_diagnostic(diagnostic, linter_config)
+          end
+
+          @diagnostics_to_clear -= @current_diagnostics.keys
+        end
+
+        #: () -> void
+        def reload_configuration
+          @config = ::Rubydex::Config.load(@workspace_path) #: ::Rubydex::Config
+          @runner = ::Rubydex::Linter::Runner.new(@graph, custom_rules: @custom_rules, config: @config.linter) #: ::Rubydex::Linter::Runner
+        end
+
+        private
+
+        #: (::Rubydex::Diagnostic, ::Rubydex::LinterConfig) -> ::RubyLsp::Interface::Diagnostic
+        def to_lsp_diagnostic(diagnostic, linter_config)
+          location = diagnostic.location
+          rule = diagnostic.rule
+
+          ::RubyLsp::Interface::Diagnostic.new(
+            message: diagnostic.message,
+            source: "Rubydex",
+            code: rule.rule_name,
+            severity: DIAGNOSTIC_SEVERITIES.fetch(rule.severity(linter_config)),
+            range: lsp_range(location),
+            related_information: diagnostic.related_information.map do |information|
+              ::RubyLsp::Interface::DiagnosticRelatedInformation.new(
+                location: ::RubyLsp::Interface::Location.new(
+                  uri: information.location.uri,
+                  range: lsp_range(information.location),
+                ),
+                message: information.message,
+              )
+            end,
+          )
+        end
+
+        #: (::Rubydex::Location) -> ::RubyLsp::Interface::Range
+        def lsp_range(location)
+          ::RubyLsp::Interface::Range.new(
+            start: ::RubyLsp::Interface::Position.new(
+              line: location.start_line,
+              character: location.start_column,
+            ),
+            end: ::RubyLsp::Interface::Position.new(
+              line: location.end_line,
+              character: location.end_column,
+            ),
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/cli/command/console.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rubydex/cli/command"
+
+module Rubydex
+  module CLI
+    # `rdx console` — opens an IRB session with a populated graph for the current workspace.
+    class Command
+      class Console < Command
+        command "console"
+        summary "Open an interactive session with a populated graph for the current workspace"
+
+        #: -> void
+        def run
+          parse_options!
+
+          start_irb(build_graph($stderr))
+        end
+
+        private
+
+        # Starts IRB with `graph` in scope.
+        #
+        #: (Rubydex::Graph graph) -> void
+        def start_irb(graph)
+          require_irb
+
+          IRB.setup(nil)
+          IRB.conf[:IRB_NAME] = "rubydex"
+
+          # The session uses IRB's own workspace rather than a binding captured here: `IRB::WorkSpace`
+          # derives its binding from a copy of `IRB::TOPLEVEL_BINDING`, so `self` is `main` and
+          # `class Foo; end` at the prompt defines `::Foo`, exactly as in a stock `irb`. A binding
+          # captured inside this class would make `self` the command object instead.
+          workspace = IRB::WorkSpace.new
+          workspace.local_variable_set(:graph, graph)
+          IRB::Irb.new(workspace).run(IRB.conf)
+        end
+
+        # `irb` is a development dependency rather than a runtime one, so a missing gem is reported
+        # instead of raised. Only a missing `irb` is reported that way: IRB loads `reline`, which
+        # needs `fiddle` on Windows, and that failure has to surface as itself rather than as a
+        # missing `irb`.
+        #: -> void
+        def require_irb
+          require "irb"
+        rescue LoadError => e
+          raise unless e.path == "irb"
+
+          abort("Interactive mode requires `irb` to be in the bundle")
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/cli/command/lint/explain.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "rubydex"
+require "rubydex/linter/rule_loader"
+
+module Rubydex
+  module CLI
+    class Command
+      class Lint
+        # `rdx lint explain <RULE>` — prints documentation for rules with a matching name.
+        class Explain < Command
+          BASE_RULE_NAME = "Rubydex::Linter::CustomRule" #: String
+          BASE_RULE_PATH = File.expand_path("../../../linter/custom_rule.rb", __dir__) #: String
+
+          class << self
+            #: -> String
+            def usage_form
+              "lint explain <RULE>"
+            end
+          end
+
+          #: -> void
+          def run
+            parse_options!
+
+            rule_name = argv.shift
+            abort_with_usage("`lint explain` requires a rule name argument") unless rule_name
+            abort_with_usage("unexpected argument: #{argv.first}") unless argv.empty?
+
+            workspace_path = current_workspace_path
+
+            graph = Rubydex::Graph.configure_for_workspace(workspace_path)
+            graph.index_all([BASE_RULE_PATH, *Rubydex::Linter::RuleLoader.paths(workspace_path)])
+            graph.resolve
+
+            base_rule = graph[BASE_RULE_NAME]
+            abort("Base rule class #{BASE_RULE_NAME} is not found. This is likely an issue in Rubydex itself") unless base_rule.is_a?(Rubydex::Class)
+
+            rule_declarations = base_rule.descendants.grep(Rubydex::Class) #: as Array[Rubydex::Class]
+            matched_rule_names = rule_declarations.filter_map do |declaration|
+              declaration_name = declaration.name
+              next unless declaration_name
+              next if declaration_name == BASE_RULE_NAME
+              next unless declaration_name.end_with?(rule_name)
+
+              declaration
+            end
+            abort("Rule does not exist: #{rule_name}") if matched_rule_names.empty?
+
+            puts(matched_rule_names.sort_by(&:name).map { |rule| documentation_for(rule) }.join("\n"))
+          end
+
+          private
+
+          #: (Rubydex::Class rule) -> String
+          def documentation_for(rule)
+            rule_name = rule.name #: as !nil
+            documentation = rule.definitions.flat_map do |definition|
+              definition.comments.map { |comment| comment.string.gsub(/^#\s*/, "") }
+            end.join("\n")
+
+            return "#{rule_name}: no documentation available." if documentation.empty?
+
+            <<~DOCUMENTATION
+              #{rule_name}
+
+              #{documentation}
+            DOCUMENTATION
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/cli/command/lint.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "rubydex/cli/command"
+
+module Rubydex
+  module CLI
+    # `rdx lint` — discovers project and dependency rules and runs them against the current workspace.
+    class Command
+      class Lint < Command
+        command "lint"
+        summary "Run semantic lint rules in the current workspace"
+
+        #: -> void
+        def run
+          if argv.first == "explain"
+            argv.shift
+            require "rubydex/cli/command/lint/explain"
+            Explain.new(argv).run
+            return
+          end
+
+          parse_options! do |parser|
+            parser.separator("")
+            parser.separator("Commands:")
+            parser.separator("  explain <RULE>  Print documentation for matching linter rules")
+            parser.separator("")
+            parser.separator("Options:")
+          end
+
+          abort_with_usage("unexpected argument: #{argv.first}") unless argv.empty?
+          workspace_path = current_workspace_path
+
+          # Keep top-level help lightweight: command discovery loads this file before the native
+          # extension, while linter support is only needed when this command runs.
+          require "rubydex/linter"
+
+          custom_rules = load_linter_rules(workspace_path)
+          warn_unknown_rules(custom_rules)
+
+          graph = build_graph($stderr, workspace_path:, config:)
+          runner = Rubydex::Linter::Runner.new(graph, custom_rules:, config: linter_config)
+          $stderr.puts("Linting...")
+          diagnostics = runner.run
+          by_severity = diagnostics.group_by { |diagnostic| diagnostic.rule.severity(linter_config) }
+
+          if diagnostics.empty?
+            print_summary(graph.documents.count, by_severity)
+            return
+          end
+
+          print_offenses(by_severity, graph)
+          exit(1) if by_severity[Rubydex::Severity::Error]&.any?
+        end
+
+        private
+
+        #: -> Rubydex::Config
+        def config
+          @config ||= Rubydex::Config.load(current_workspace_path) #: Rubydex::Config?
+        end
+
+        #: -> Rubydex::LinterConfig
+        def linter_config
+          @linter_config ||= config.linter #: Rubydex::LinterConfig?
+        end
+
+        #: (Array[singleton(Rubydex::Linter::CustomRule)] custom_rule_classes) -> void
+        def warn_unknown_rules(custom_rule_classes)
+          known_rule_names = (Rubydex::Rules::ALL + custom_rule_classes).map(&:rule_name).uniq.sort
+          unknown_rule_names = linter_config.rules.keys.reject { |name| known_rule_names.include?(name) }.sort
+          return if unknown_rule_names.empty?
+
+          formatted_names = unknown_rule_names.map { |name| "`#{name}`" }.join(", ")
+          warn(
+            "warning: linter config references rules that were not loaded: #{formatted_names}. " \
+              "Known rules: #{known_rule_names.join(", ")}",
+          )
+        end
+
+        #: (String workspace_path) -> Array[singleton(Rubydex::Linter::CustomRule)]
+        def load_linter_rules(workspace_path)
+          Rubydex::Linter::RuleLoader.load(workspace_path)
+          Rubydex::Linter::CustomRule.subclasses
+        rescue Rubydex::Linter::RuleLoadError => error
+          abort(error.message)
+        end
+
+        #: (Hash[singleton(Severity::Base), Array[Diagnostic]], Graph) -> void
+        def print_offenses(grouped_diagnostics, graph)
+          puts("Offenses:")
+          puts
+
+          Rubydex::Severity::ALL.each do |severity|
+            diagnostics = grouped_diagnostics[severity]
+            next unless diagnostics
+
+            diagnostics.sort_by! do |diagnostic|
+              location = diagnostic.location
+
+              [
+                location.uri,
+                location.start_line,
+                location.start_column,
+                location.end_line,
+                location.end_column,
+                diagnostic.rule.rule_name,
+                diagnostic.message,
+              ]
+            end
+
+            diagnostics.each do |diagnostic|
+              puts(format_linter_diagnostic(severity, diagnostic, workspace_path: graph.workspace_path))
+              print_source_excerpt(diagnostic.location)
+              puts
+            end
+          end
+
+          print_summary(graph.documents.count, grouped_diagnostics)
+          puts("For more information about a rule, run `rdx lint explain RuleName`.")
+        end
+
+        #: (Location location, workspace_path: String) -> String
+        def format_linter_location(location, workspace_path:)
+          display_location = location.to_display
+          path = Rubydex::Linter::Helpers::PathHelpers.display_path(display_location, workspace: workspace_path)
+
+          "#{path}:#{display_location.start_line}:#{display_location.start_column}"
+        end
+
+        #: (singleton(Severity::Base), Diagnostic, workspace_path: String) -> String
+        def format_linter_diagnostic(severity, diagnostic, workspace_path:)
+          content = +"#{format_linter_location(diagnostic.location, workspace_path:)}: " \
+            "#{severity.value}: #{diagnostic.rule.rule_name}: #{diagnostic.message}"
+
+          diagnostic.related_information.each do |information|
+            content << "\n  #{format_linter_location(information.location, workspace_path:)}: #{information.message}"
+          end
+
+          content
+        end
+
+        #: (Location location) -> void
+        def print_source_excerpt(location)
+          line = source_line_for(location)
+          return unless line
+
+          end_column = location.end_line == location.start_line ? location.end_column : line.length
+          carets = "^" * [end_column - location.start_column, 1].max
+
+          puts
+          puts(line)
+          puts("#{" " * location.start_column}#{carets}")
+        end
+
+        #: (Location location) -> String?
+        def source_line_for(location)
+          source_lines_for(location.to_file_path)[location.start_line]
+        rescue Errno::ENOENT, Errno::EACCES, Rubydex::Location::NotFileUriError
+          nil
+        end
+
+        #: (String path) -> Array[String]
+        def source_lines_for(path)
+          @source_lines_cache ||= {} #: Hash[String, Array[String]]?
+          @source_lines_cache[path] ||= File.readlines(path, chomp: true)
+        end
+
+        #: (Integer, Hash[singleton(Severity::Base), Array[Diagnostic]]) -> void
+        def print_summary(file_count, grouped_diagnostics)
+          if grouped_diagnostics.empty?
+            puts("#{file_count} #{pluralize("file", file_count)} inspected, no offenses detected")
+            return
+          end
+
+          offense_count = grouped_diagnostics.each_value.sum(&:length)
+
+          error_count = grouped_diagnostics[Rubydex::Severity::Error]&.length || 0
+          warning_count = grouped_diagnostics[Rubydex::Severity::Warning]&.length || 0
+          information_count = grouped_diagnostics[Rubydex::Severity::Information]&.length || 0
+          hint_count = grouped_diagnostics[Rubydex::Severity::Hint]&.length || 0
+
+          severity_summary = [
+            "#{error_count} #{pluralize("error", error_count)}",
+            "#{warning_count} #{pluralize("warning", warning_count)}",
+            "#{information_count} info",
+            "#{hint_count} #{pluralize("hint", hint_count)}",
+          ].join(", ")
+
+          puts(
+            "#{file_count} #{pluralize("file", file_count)} inspected, " \
+              "#{offense_count} #{pluralize("offense", offense_count)} detected: #{severity_summary}",
+          )
+        end
+
+        #: (String word, Integer count) -> String
+        def pluralize(word, count)
+          count == 1 ? word : "#{word}s"
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/cli/command/mcp.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rubydex/cli/command"
+
+module Rubydex
+  module CLI
+    # `rdx mcp [PATH]` — runs the MCP server for AI assistants. The workspace defaults to the
+    # current directory.
+    class Command
+      class Mcp < Command
+        command "mcp"
+        arguments "[PATH]"
+        summary "Run the MCP server for AI assistants (workspace defaults to the current dir)"
+
+        #: -> void
+        def run
+          parse_options!
+
+          path = argv.shift || Dir.pwd
+          abort_with_usage("unexpected argument: #{argv.first}") unless argv.empty?
+
+          # The MCP server manages its own graph lifecycle for the given workspace, so it does not go
+          # through `build_graph`.
+          require "rubydex/mcp_server"
+          Rubydex::MCPServer.run(path)
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/cli/command/query.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "rubydex/cli/command"
+
+module Rubydex
+  module CLI
+    # `rdx query <CYPHER>` — runs a Cypher query against the workspace graph and prints the result.
+    # `--schema` describes the queryable schema instead, which needs no graph.
+    class Command
+      class Query < Command
+        command "query"
+        arguments "<CYPHER>"
+        summary <<~TEXT
+          Run a Cypher query against the workspace graph and print the result.
+          Use `query --schema` to describe the queryable schema (labels,
+          relationships, properties) without indexing the workspace.
+        TEXT
+
+        #: -> void
+        def run
+          schema = false
+          format = "table"
+
+          parse_options!(options: true) do |parser|
+            parser.on("--schema", "Describe the queryable schema instead of running a query") { schema = true }
+            parser.on("--format FORMAT", ["table", "json"], "Output format (table or json)") do |value|
+              format = value
+            end
+          end
+
+          query = argv.shift
+
+          if schema
+            warn("warning: ignoring query argument because `--schema` was given") if query
+            # The schema is static, so describe it without building a graph.
+            print(Rubydex::Query.schema(format))
+            return
+          end
+
+          if query.nil? || query.empty?
+            abort_with_usage("`query` requires a Cypher query argument (or pass `--schema`)")
+          end
+
+          # Parse the query up front so a malformed query fails fast, before the expensive indexing.
+          parsed = parse_query(query)
+
+          # Progress goes to stderr so stdout carries only the result (e.g. for piping a query's JSON).
+          graph = build_graph($stderr)
+
+          begin
+            result = parsed.run(graph)
+          rescue Rubydex::QueryExecutionError => e
+            abort(e.message)
+          end
+
+          print(result.render(format))
+        end
+
+        private
+
+        #: (String query) -> Rubydex::Query
+        def parse_query(query)
+          Rubydex::Query.parse(query)
+        rescue Rubydex::QuerySyntaxError => e
+          abort(e.message)
+        end
+      end
+    end
+  end
+end