rubydex 0.2.9 → 0.4.0

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "rubydex/cli/command"
+
+module Rubydex
+  module CLI
+    class Command
+      # `rdx skill [ID]` — lists available skill ids, or loads and prints a skill's body by id.
+      class Skill < Command
+        command "skill"
+        arguments "[ID]"
+        summary <<~TEXT
+          Load a Rubydex skill from the library by id. With no id, list the available skills.
+        TEXT
+
+        #: -> void
+        def run
+          parse_options!
+
+          id = argv.shift
+          abort_with_usage("unexpected argument: #{argv.first}") unless argv.empty?
+
+          id ? print_skill(id) : list_skills
+        rescue Rubydex::SkillError => e
+          abort(e.message)
+        end
+
+        private
+
+        #: -> void
+        def list_skills
+          ids = registry.ids
+
+          if ids.empty?
+            puts(available_skills)
+            return
+          end
+
+          ids.each { |id| puts(id) }
+        end
+
+        #: (String id) -> void
+        def print_skill(id)
+          puts(registry.fetch(id).body)
+        rescue Rubydex::UnknownSkillError => e
+          abort("#{e.message}. #{available_skills}")
+        end
+
+        #: -> String
+        def available_skills
+          ids = registry.ids
+
+          ids.empty? ? "No skills are available." : "Available skills: #{ids.join(", ")}"
+        end
+
+        #: -> Rubydex::SkillRegistry
+        def registry
+          require "rubydex/skill_registry"
+          @registry ||= Rubydex::SkillRegistry.load(skills_directory)
+        end
+
+        #: -> String
+        def skills_directory
+          File.expand_path("../../../../skills", __dir__)
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/cli/command.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Rubydex
+  module CLI
+    # Base class for `rdx` subcommands. A subcommand parses its own options out of `argv` and, when
+    # it needs one, builds the workspace graph through {#build_graph}.
+    #
+    # Subclasses live one per file in `lib/rubydex/cli/command/` and describe themselves with a
+    # small DSL, which supplies both the name they are dispatched under and their entry in
+    # `rdx help`:
+    #
+    #     class Query < Command
+    #       command "query"
+    #       arguments "<CYPHER>"
+    #       summary "Run a Cypher query against the workspace graph and print the result."
+    #     end
+    #
+    # There is no registration list to keep in step: {.all} loads every file in that directory and
+    # discovers the commands through `Class#subclasses`.
+    class Command
+      class << self
+        # The subcommand name declared by {.command}. `nil` for a class that declares none, which is
+        # how an abstract intermediate class opts out of being dispatched.
+        #: String?
+        attr_reader :command_name
+
+        # Declares the subcommand name this class is dispatched under.
+        #
+        # Deliberately not called `name`: that would shadow `Class#name`, which Ruby uses when it
+        # builds error messages, so a `NoMethodError` on a command would report "an instance of
+        # query" instead of naming the class.
+        #: (String value) -> void
+        def command(value)
+          # Deliberately checked against {.declared} rather than {.find}: this runs while a command
+          # file is still being loaded, and `find` would glob in every other command file first.
+          clash = declared.find { |other| !other.equal?(self) && other.command_name == value }
+          raise ArgumentError, "command `#{value}` is already declared by #{clash}" if clash
+
+          @command_name = value #: String?
+        end
+
+        # Declares the argument spec shown after the command name in `rdx help`, e.g. `"<CYPHER>"`.
+        # Called without an argument, returns the declared spec.
+        #: (?String? spec) -> String?
+        def arguments(spec = nil)
+          return @arguments unless spec
+
+          @arguments = spec #: String?
+        end
+
+        # Declares the description shown in `rdx help`. May span several lines, which are aligned
+        # under the first when the command list is rendered. Called without an argument, returns the
+        # declared description.
+        #: (?String? text) -> String?
+        def summary(text = nil)
+          return @summary unless text
+
+          @summary = text.strip #: String?
+        end
+
+        # How the command is spelled in a usage line, e.g. `"query <CYPHER>"`.
+        #: -> String
+        def usage_form
+          [command_name, arguments].compact.join(" ")
+        end
+
+        # The subcommands that are currently loaded, in alphabetical order. Loads nothing itself, so
+        # it is safe to call while a command file is still being evaluated.
+        #: -> Array[singleton(Command)]
+        def declared
+          Command.subclasses.select(&:command_name).sort_by(&:command_name)
+        end
+
+        # Every subcommand, in alphabetical order. Loads the command files first, so the answer does
+        # not depend on what happens to have been required already.
+        #: -> Array[singleton(Command)]
+        def all
+          Dir.glob(File.expand_path("command/*.rb", __dir__)).sort.each { |file| require(file) }
+
+          declared
+        end
+
+        # The subcommand declared under `name`, if any.
+        #: (String? name) -> singleton(Command)?
+        def find(name)
+          all.find { |command| command.command_name == name }
+        end
+      end
+
+      #: (Array[String] argv) -> void
+      def initialize(argv)
+        @argv = argv
+      end
+
+      #: -> void
+      def run
+        raise NotImplementedError, "#{self.class} must implement #run"
+      end
+
+      private
+
+      #: Array[String]
+      attr_reader :argv
+
+      #: (String message) -> void
+      def abort_with_usage(message)
+        warn(message)
+        warn("")
+        warn(@parser)
+        exit(1)
+      end
+
+      # Parses this command's options out of `argv`, with a banner derived from the command's own
+      # declaration. `-h`/`--help` prints the parser and exits, so every subcommand documents itself
+      # the same way. Pass `options: true` when the command accepts options beyond `--help`.
+      #
+      # A bad option reports the message and the usage text, so every subcommand rejects bad input
+      # the same way.
+      #: (?options: bool) ?{ (OptionParser parser) -> void } -> void
+      def parse_options!(options: false)
+        banner = +"Usage: rdx #{self.class.usage_form}"
+        banner << " [options]" if options
+
+        @parser = OptionParser.new do |p|
+          p.banner = banner
+          yield(p) if block_given?
+          p.on("-h", "--help", "Show this help") do
+            puts(p)
+            exit
+          end
+        end
+
+        @parser.parse!(argv)
+      rescue OptionParser::ParseError => e
+        abort_with_usage(e.message)
+      end
+
+      #: -> String
+      def current_workspace_path
+        Bundler.root.to_s
+      rescue Bundler::GemfileNotFound
+        Dir.pwd
+      end
+
+      # Builds the workspace graph, sending progress messages to `progress_io`.
+      #: (IO progress_io, ?workspace_path: String, ?config: Rubydex::Config) -> Rubydex::Graph
+      def build_graph(progress_io, workspace_path: Dir.pwd, config: Rubydex::Config.load(workspace_path))
+        graph = Rubydex::Graph.new
+        graph.load_config(config)
+        with_timer(progress_io, "Indexing workspace...") { graph.index_workspace }
+        with_timer(progress_io, "Resolving graph...") { graph.resolve }
+        graph
+      end
+
+      #: [T] (IO io, String message) { -> T } -> T
+      def with_timer(io, message)
+        io.print(message)
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+        result = yield
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - start
+        io.puts(" finished in #{duration.round(2)}ms")
+        result
+      end
+    end
+  end
+end

data/lib/rubydex/cli.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Rubydex
+  # Command-line entry point for the `rdx` executable. It handles the top-level flags, resolves the
+  # subcommand and delegates to it, which keeps `exe/rdx` a thin shim.
+  #
+  # Subcommands live one per file in `lib/rubydex/cli/command/` and declare the name they answer to
+  # (see {CLI::Command}). Both dispatch and the `rdx help` command list are driven by that
+  # declaration, so adding a subcommand means adding a file — there is no dispatch table or usage
+  # text to keep in step.
+  module CLI
+    HEADER = "Usage: rdx <command> [options]" #: String
+    FOOTER = "Run `rdx <command> --help` for command-specific options." #: String
+
+    # `help` is served by the top-level flags rather than by a Command subclass, so its entry is
+    # listed here to keep it in the generated command list.
+    HELP_ENTRY = ["help", "Show this help message"].freeze #: [String, String]
+
+    class << self
+      # Entry point used by `exe/rdx`.
+      #: (?Array[String] argv) -> void
+      def start(argv = ARGV)
+        return if handle_top_level_flags(argv)
+
+        # Everything past this point needs the native extension.
+        require "rubydex"
+
+        dispatch(argv.shift, argv)
+      end
+
+      private
+
+      # Reports `message`, then the top-level usage text, and exits non-zero.
+      #: (String message) -> void
+      def abort_with_usage(message)
+        warn(message)
+        warn("")
+        warn(usage)
+        exit(1)
+      end
+
+      # The top-level usage text, built from the declared commands.
+      #: -> String
+      def usage
+        require "rubydex/cli/command"
+
+        entries = Command.all.map { |command| [command.usage_form, command.summary.to_s] }
+        entries << HELP_ENTRY.dup
+
+        width = entries.map { |form, _| form.length }.max + 3
+        lines = entries.flat_map { |form, summary| describe(form, summary, width) }
+
+        "#{[HEADER, "", "Commands:", *lines, "", FOOTER].join("\n")}\n"
+      end
+
+      # Renders one entry of the command list, aligning any continuation lines of `summary` under
+      # the first.
+      #: (String form, String summary, Integer width) -> Array[String]
+      def describe(form, summary, width)
+        first, *rest = summary.split("\n")
+
+        ["  #{form.ljust(width)}#{first}", *rest.map { |line| "#{" " * (width + 2)}#{line}" }]
+      end
+
+      # Handles `--version` / `--help` / a bare invocation, returning whether the invocation was
+      # handled so `start` returns exactly once rather than exiting from inside every branch.
+      #: (Array[String] argv) -> bool
+      def handle_top_level_flags(argv)
+        case argv.first
+        when "--version", "version"
+          require "rubydex/version"
+          puts("v#{Rubydex::VERSION}")
+          true
+        when nil, "-h", "--help", "help"
+          puts(usage)
+          true
+        else
+          false
+        end
+      end
+
+      #: (String? name, Array[String] argv) -> void
+      def dispatch(name, argv)
+        require "rubydex/cli/command"
+
+        command_class = Command.find(name)
+        abort_with_usage("unknown command: #{name}") unless command_class
+
+        command_class.new(argv).run
+      end
+    end
+  end
+end

data/lib/rubydex/config.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Rubydex
+  # The linter's settings, read from the `[linter]` section of the configuration file.
+  class LinterConfig
+    # The configured rules, keyed by rule name. Only rules the configuration file mentions appear here, so a rule that
+    # was never configured is absent rather than present with its defaults.
+    #
+    #: Hash[String, RuleConfig]
+    attr_reader :rules
+
+    #: (Hash[String, RuleConfig]) -> void
+    def initialize(rules)
+      @rules = rules.freeze
+      freeze
+    end
+
+    #: (singleton(Rule) rule_class) -> bool
+    def rule_enabled?(rule_class)
+      rule = @rules[rule_class.rule_name]
+      !rule || rule.enabled?
+    end
+
+    #: (singleton(Rule) rule_class) -> Array[String]
+    def excludes_for(rule_class)
+      @rules[rule_class.rule_name]&.exclude_patterns || []
+    end
+
+    #: (singleton(Rule) rule_class) -> singleton(Severity::Base)?
+    def severity_for(rule_class)
+      @rules[rule_class.rule_name]&.severity
+    end
+  end
+
+  # The settings of a single linter rule, read from a `[linter.rules.RuleName]` table.
+  class RuleConfig
+    #: String
+    attr_reader :name
+
+    #: Array[String]
+    attr_reader :exclude_patterns
+
+    #: singleton(Severity::Base)?
+    attr_reader :severity
+
+    #: (String, bool, ?Array[String], ?singleton(Severity::Base)?) -> void
+    def initialize(name, enabled, exclude_patterns = [], severity = nil)
+      @name = name
+      @enabled = enabled
+      @exclude_patterns = exclude_patterns
+      @severity = severity
+    end
+
+    #: () -> bool
+    def enabled?
+      @enabled
+    end
+  end
+end

data/lib/rubydex/diagnostic.rb

@@ -2,7 +2,7 @@
 
 module Rubydex
   class Diagnostic
-    #: Symbol
+    #: singleton(Rule)
     attr_reader :rule
 
     #: String
@@ -11,11 +11,20 @@ module Rubydex
     #: Location
     attr_reader :location
 
-    #: (rule: Symbol, message: String, location: Location) -> void
-    def initialize(rule:, message:, location:)
+    #: Array[RelatedInformation]
+    attr_reader :related_information
+
+    #: (
+    #|   rule: singleton(Rule),
+    #|   message: String,
+    #|   location: Location,
+    #|   ?related_information: Array[RelatedInformation],
+    #| ) -> void
+    def initialize(rule:, message:, location:, related_information: [])
       @rule = rule
       @message = message
       @location = location
+      @related_information = related_information
     end
   end
 end

data/lib/rubydex/errors.rb

@@ -6,6 +6,47 @@ module Rubydex
   # Raised when `MethodAliasDefinition#target` walks an alias chain that loops back on itself.
   class AliasCycleError < Error; end
 
-  # Raised by `Graph#load_config` when the requested config file does not exist, cannot be read, or is malformed
+  # Raised by `Config.load` when the workspace does not exist, or when its config file cannot be read or is malformed.
+  # A workspace with no config file at all is not an error.
   class ConfigError < Error; end
+
+  # Raised by `Skill.load` when the file cannot be read, is missing frontmatter, has malformed YAML, or lacks the
+  # required `name` or `description` fields.
+  # Every failure to produce a Skill is a `SkillError`, so a caller rescues one class instead
+  # of the union of what `File.read` and Psych happen to raise.
+  class SkillError < Error; end
+
+  # Raised by `SkillRegistry#fetch` when the library has no skill under the requested id.
+  class UnknownSkillError < SkillError; end
+
+  # Raised by `SkillRegistry.load` when the skill directory doesn't exist.
+  class UnknownSkillDirectoryError < SkillError; end
+
+  # Raised when a Cypher query cannot be parsed or cannot run. `Rubydex::Query` raises one of its
+  # subclasses; rescue this class to catch either.
+  class QueryError < Error; end
+
+  # Raised by `Query.parse` when the query is not valid Cypher.
+  class QuerySyntaxError < QueryError; end
+
+  # Raised by `Query#run` when a parsed query fails while it runs against a graph, for example
+  # because it names an unknown property or relationship type.
+  class QueryExecutionError < QueryError; end
+
+  # Raised when a query result names a node that the graph no longer holds, because the graph
+  # changed after the query ran. Reading the rows would silently turn that column from a
+  # `Declaration`, `Definition`, or `Document` handle into a plain String, so it raises instead.
+  # `render`, `columns`, `size`, and `empty?` still work, because they read the executed result set
+  # and never touch the graph.
+  #
+  # The check runs while a row is built, so it covers the rows that a walk has not reached yet. Two
+  # cases fall outside it:
+  #
+  # - A handle that a walk already handed out. Such a handle resolves against the graph on each
+  #   call, so a later change to the graph can make it stale. Handles from `Graph#[]` share that
+  #   property. This error says nothing about them.
+  # - A re-index that keeps the ids. A declaration id comes from the name, so a file indexed again
+  #   under the same names still resolves, and this error does not fire, even though the
+  #   definitions and ancestors behind that name may differ.
+  class StaleQueryResultError < QueryError; end
 end

data/lib/rubydex/graph.rb

@@ -7,9 +7,16 @@ module Rubydex
   class Graph
     INDEXABLE_EXTENSIONS = [".rb", ".rake", ".rbs", ".ru"].freeze
 
-    #: (?workspace_path: String?) -> void
-    def initialize(workspace_path: nil)
-      self.workspace_path = workspace_path if workspace_path
+    class << self
+      # Creates a new graph with the loaded configuration. For use cases where the graph must be shared between
+      # different tools, do not use this. Create and own a `Config` object instead.
+      #
+      #: (String) -> instance
+      def configure_for_workspace(workspace_path)
+        graph = new
+        graph.load_config(Config.load(workspace_path))
+        graph
+      end
     end
 
     # Index all files and dependencies of the workspace that exists in `workspace_path`

data/lib/rubydex/linter/custom_rule.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module Linter
+    # Base class for semantic lint rules, which collect their diagnostics by walking a resolved graph.
+    # @abstract
+    class CustomRule < Rule
+      #: Graph
+      attr_reader :graph
+
+      #: LinterConfig
+      attr_reader :config
+
+      #: Array[Diagnostic]
+      attr_reader :diagnostics
+
+      #: (Graph, config: LinterConfig) -> void
+      def initialize(graph, config:)
+        super()
+        @graph = graph
+        @config = config
+        @diagnostics = [] #: Array[Diagnostic]
+      end
+
+      # @abstract
+      #: () -> void
+      def lint
+        raise NotImplementedError, "Subclasses must implement the lint method"
+      end
+
+      # Anchors a diagnostic on a definition's name token, falling back to its full range when no name location exists.
+      #: (Definition) -> Location
+      def diagnostic_location(definition)
+        definition.name_location || definition.location
+      end
+
+      # Returns every class inheriting from +base_name+, excluding the base class itself.
+      #: (String) -> Enumerable[Rubydex::Class]
+      def child_classes(base_name)
+        required_namespace(base_name).descendants.lazy.filter_map do |child_declaration|
+          next unless child_declaration.is_a?(Rubydex::Class)
+          next if child_declaration.name == base_name
+
+          child_declaration
+        end
+      end
+
+      #: (String) -> Namespace
+      def required_namespace(name)
+        declaration = graph[name]
+        return declaration if declaration.is_a?(Namespace)
+
+        raise MissingGraphDependencyError.new(rule_name, "`#{name}`")
+      end
+
+      #: (Namespace, String) -> Rubydex::Method
+      def required_method(namespace, method_name)
+        method = namespace.find_member(method_name)
+        return method if method.is_a?(Rubydex::Method)
+
+        raise MissingGraphDependencyError.new(rule_name, "`#{namespace.name}##{method_name}`")
+      end
+
+      #: () -> String
+      def rule_name
+        self.class.rule_name
+      end
+
+      protected
+
+      #: (
+      #|   String,
+      #|   Location,
+      #|   ?related_information: Array[RelatedInformation],
+      #| ) -> void
+      def add_diagnostic(message, location, related_information: [])
+        @diagnostics << Diagnostic.new(
+          rule: self.class,
+          message: message,
+          location: location,
+          related_information: related_information,
+        )
+      end
+    end
+
+    class MissingGraphDependencyError < StandardError
+      #: (String, String) -> void
+      def initialize(rule_name, dependency)
+        super(
+          "Rubydex linter rule `#{rule_name}` requires #{dependency} to exist in the Rubydex graph. " \
+            "This is a rule setup error, not a clean lint result; ensure the source that defines " \
+            "the dependency is indexed and Rubydex can resolve it.",
+        )
+      end
+    end
+  end
+end

data/lib/rubydex/linter/helpers/path_helpers.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "uri"
+
+module Rubydex
+  module Linter
+    module Helpers
+      # @requires_ancestor: Rubydex::Linter::CustomRule
+      module PathHelpers
+        EXCLUDE_FNMATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH #: Integer
+        TEST_PATHS = ["test/**", "**/test/**", "**/*_test.rb"].freeze
+
+        class << self
+          #: (String, Array[String], workspace: String, ?flags: Integer) -> bool
+          def path_matches_patterns?(path, patterns, workspace:, flags: 0)
+            return false unless path == workspace || path.start_with?("#{workspace}/")
+
+            relative_path = path.delete_prefix("#{workspace}/")
+            patterns.any? { |pattern| File.fnmatch?(pattern, relative_path, flags) }
+          end
+
+          # Returns the path to show users for a location: relative to the workspace for files inside it, the absolute
+          # path for files outside it (dependencies, for example) and the URI opaque for non file URIs, so that
+          # `untitled:Untitled-1` displays as `Untitled-1`.
+          #
+          #: (Location, workspace: String) -> String
+          def display_path(location, workspace:)
+            path = location.to_file_path
+            return path unless path == workspace || path.start_with?("#{workspace}/")
+
+            Pathname.new(path).relative_path_from(workspace).to_s
+          rescue Location::NotFileUriError
+            URI(location.uri).opaque || location.uri
+          end
+        end
+
+        #: (Enumerable[Rubydex::Definition], Array[String]) -> Array[Rubydex::Definition]
+        def reject_definitions_in_paths(definitions, excluded_patterns)
+          workspace = graph.workspace_path
+
+          definitions.reject do |definition|
+            path = path_for_definition(definition)
+            path.nil? || (path != workspace && !path.start_with?("#{workspace}/")) ||
+              path_matches_patterns?(path, excluded_patterns)
+          end
+        end
+
+        #: (Enumerable[Rubydex::Definition], Array[String]) -> Array[Rubydex::Definition]
+        def select_definitions_in_paths(definitions, patterns)
+          definitions.select do |definition|
+            path = path_for_definition(definition)
+            path && path_matches_patterns?(path, patterns)
+          end
+        end
+
+        private
+
+        #: (String, Array[String]) -> bool
+        def path_matches_patterns?(path, patterns)
+          PathHelpers.path_matches_patterns?(path, patterns, workspace: graph.workspace_path)
+        end
+
+        #: (String) -> bool
+        def test_path?(path)
+          path_matches_patterns?(path, TEST_PATHS)
+        end
+
+        #: (Rubydex::Definition) -> String?
+        def path_for_definition(definition)
+          definition.location.to_file_path
+        rescue Location::NotFileUriError
+          nil
+        end
+      end
+    end
+  end
+end