rubydex 0.3.0 → 0.4.1

data/lib/rubydex/rules/invalid_method_visibility.rb

@@ -0,0 +1,28 @@
+# typed: strict
+# frozen_string_literal: true
+
+# This file is generated by `generate_ruby_rules.rs`. Do not edit this manually.
+
+module Rubydex
+  module Rules
+    # Method visibility operations that depend on dynamic values cannot be reasoned about statically because they
+    # depend on runtime values. The program may still be valid, but the quality of the analysis degrades.
+    #
+    # ```ruby
+    # var.private :foo
+    # ^^^ Invalid method visibility. This might be correct, but it cannot be understood by the analysis.
+    #
+    # private(var)
+    #         ^^^ Invalid method visibility.
+    # ```
+    class InvalidMethodVisibility < Rule
+      class << self
+        # @override
+        #: -> singleton(Severity::Base)
+        def default_severity
+          Severity::Warning
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/rules/parse_error.rb

@@ -0,0 +1,25 @@
+# typed: strict
+# frozen_string_literal: true
+
+# This file is generated by `generate_ruby_rules.rs`. Do not edit this manually.
+
+module Rubydex
+  module Rules
+    # A parse error represents invalid Ruby syntax and a program that will fail to execute. For example, a missing
+    # `end`, an unterminated string, a missing parenthesis.
+    #
+    # ```ruby
+    # class Foo
+    # ^^^^^ Syntax error. Missing end token
+    # ```
+    class ParseError < Rule
+      class << self
+        # @override
+        #: -> singleton(Severity::Base)
+        def default_severity
+          Severity::Error
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/rules/parse_warning.rb

@@ -0,0 +1,28 @@
+# typed: strict
+# frozen_string_literal: true
+
+# This file is generated by `generate_ruby_rules.rs`. Do not edit this manually.
+
+module Rubydex
+  module Rules
+    # Parse warnings represent code that has valid syntax, but may not do what the developer expects. For example,
+    # local variables that are completely unused or usage in a void context (creating a line of code that does
+    # nothing).
+    #
+    # ```ruby
+    # CONST = 1
+    # CONST
+    # ^^^^^ Constant used in void context (the expression does nothing).
+    # puts CONST + 2
+    # ```
+    class ParseWarning < Rule
+      class << self
+        # @override
+        #: -> singleton(Severity::Base)
+        def default_severity
+          Severity::Warning
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/rules/top_level_mixin_self.rb

@@ -0,0 +1,27 @@
+# typed: strict
+# frozen_string_literal: true
+
+# This file is generated by `generate_ruby_rules.rs`. Do not edit this manually.
+
+module Rubydex
+  module Rules
+    # The top level of a Ruby program is the special <main> object. It is not possible to use `include self` or
+    # `extend self` on that object.
+    #
+    # ```ruby
+    # include self
+    #         ^^^^ Cannot include self at the top level
+    # extend self
+    #        ^^^^ Cannot extend self at the top level
+    # ```
+    class TopLevelMixinSelf < Rule
+      class << self
+        # @override
+        #: -> singleton(Severity::Base)
+        def default_severity
+          Severity::Information
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/rules/undefined_constant_visibility_target.rb

@@ -0,0 +1,27 @@
+# typed: strict
+# frozen_string_literal: true
+
+# This file is generated by `generate_ruby_rules.rs`. Do not edit this manually.
+
+module Rubydex
+  module Rules
+    # Undefined constant visibility target means the analysis couldn't find the definition for the constant the code is
+    # attempting to change visibility of. It could be defined through meta-programming or it indeed does not exist.
+    #
+    # ```ruby
+    # class Foo
+    #   private_constant :Bar
+    #                    ^^^ Undefined constant visibility target. The constant `Bar` is not defined.
+    # end
+    # ```
+    class UndefinedConstantVisibilityTarget < Rule
+      class << self
+        # @override
+        #: -> singleton(Severity::Base)
+        def default_severity
+          Severity::Warning
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/rules/undefined_method_visibility_target.rb

@@ -0,0 +1,27 @@
+# typed: strict
+# frozen_string_literal: true
+
+# This file is generated by `generate_ruby_rules.rs`. Do not edit this manually.
+
+module Rubydex
+  module Rules
+    # Undefined method visibility target means the analysis couldn't find the definition for the method the code is
+    # attempting to change visibility of. It could be defined through meta-programming or it indeed does not exist.
+    #
+    # ```ruby
+    # class Foo
+    #   private :bar
+    #            ^^^ Undefined method visibility target. The method `bar` is not defined.
+    # end
+    # ```
+    class UndefinedMethodVisibilityTarget < Rule
+      class << self
+        # @override
+        #: -> singleton(Severity::Base)
+        def default_severity
+          Severity::Warning
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/severity.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module Severity
+    # @abstract
+    class Base
+      class << self
+        # @abstract
+        #: () -> Symbol
+        def value
+          raise NotImplementedError, "Subclasses must implement the value method"
+        end
+      end
+    end
+
+    class Error < Base
+      class << self
+        # @override
+        #: () -> Symbol
+        def value
+          :error
+        end
+      end
+    end
+
+    class Warning < Base
+      class << self
+        # @override
+        #: () -> Symbol
+        def value
+          :warning
+        end
+      end
+    end
+
+    class Information < Base
+      class << self
+        # @override
+        #: () -> Symbol
+        def value
+          :information
+        end
+      end
+    end
+
+    class Hint < Base
+      class << self
+        # @override
+        #: () -> Symbol
+        def value
+          :hint
+        end
+      end
+    end
+
+    # All severities order based on their importance.
+    ALL = [Error, Warning, Information, Hint].freeze #: Array[singleton(Base)]
+    VALUE_MAP = ALL.to_h { |severity| [severity.value, severity] }.freeze #: Hash[Symbol, singleton(Base)]
+
+    class << self
+      #: (Symbol) -> singleton(Base)
+      def from_value(value)
+        severity = VALUE_MAP[value]
+        return severity if severity
+
+        raise ArgumentError, "Invalid severity #{value.inspect}. Expected one of: #{VALUE_MAP.keys.join(", ")}"
+      end
+    end
+  end
+end

data/lib/rubydex/skill.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "rubydex/errors"
+
+module Rubydex
+  # A skill file loaded from disk. Skill files are Markdown documents with YAML frontmatter
+  # that declare a `name` and `description`. The body is the Markdown content after the frontmatter.
+  class Skill
+    #: String
+    attr_reader :name
+
+    #: String
+    attr_reader :description
+
+    #: String
+    attr_reader :body
+
+    class << self
+      #: (String path) -> Rubydex::Skill
+      def load(path)
+        from_content(File.read(path), path:)
+      rescue SystemCallError, IOError => e
+        raise SkillError, "Cannot read skill file #{path}: #{e.message}"
+      end
+
+      #: (String content, ?path: String?) -> Rubydex::Skill
+      def from_content(content, path: nil)
+        new(**parse(content, path:))
+      end
+
+      private
+
+      #: (String content, path: String?) -> { name: String, description: String, body: String }
+      def parse(content, path:)
+        lines = content.lines
+
+        unless lines.first&.strip == "---"
+          raise SkillError, "Missing YAML frontmatter delimiter#{location(path)}"
+        end
+
+        closing_index = (1...lines.length).find { |i| lines[i].strip == "---" }
+        unless closing_index
+          raise SkillError, "Unterminated YAML frontmatter#{location(path)}"
+        end
+
+        frontmatter = lines[1...closing_index].join
+        body = lines[(closing_index + 1)..].join.strip
+
+        yaml = parse_frontmatter(frontmatter, path)
+        unless yaml.is_a?(Hash)
+          raise SkillError, "Empty or malformed YAML frontmatter#{location(path)}"
+        end
+
+        name = yaml["name"]
+        unless name.is_a?(String)
+          raise SkillError, "Missing or non-string `name` in frontmatter#{location(path)}"
+        end
+
+        description = yaml["description"]
+        unless description.is_a?(String)
+          raise SkillError, "Missing or non-string `description` in frontmatter#{location(path)}"
+        end
+
+        { name:, description:, body: }
+      end
+
+      #: (String frontmatter, String? path) -> untyped
+      def parse_frontmatter(frontmatter, path)
+        YAML.safe_load(frontmatter)
+      rescue Psych::Exception => e
+        raise SkillError, "Malformed YAML frontmatter#{location(path)}: #{e.message}"
+      end
+
+      #: (String?) -> String
+      def location(path)
+        path ? " in #{path}" : ""
+      end
+    end
+
+    #: (name: String, description: String, body: String) -> void
+    def initialize(name:, description:, body:)
+      @name = name.freeze
+      @description = description.freeze
+      @body = body.freeze
+      freeze
+    end
+  end
+end

data/lib/rubydex/skill_registry.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "rubydex/skill"
+
+module Rubydex
+  # The skills available on disk, keyed by id. `load` scans a directory for `<id>/SKILL.md` entries
+  # and records their paths.
+  # A skill file is only read when {#fetch} asks for it. Listing every description reads all skill files.
+  #
+  # The directory name is the id: it is what `rdx skill <id>` takes as a parameter.
+  class SkillRegistry
+    class << self
+      #: (String directory) -> Rubydex::SkillRegistry
+      def load(directory)
+        unless File.directory?(directory)
+          raise UnknownSkillDirectoryError, "Skill directory does not exist: #{directory}"
+        end
+
+        paths = {}
+        Dir.foreach(directory) do |entry|
+          next if entry == "." || entry == ".."
+
+          skill_path = File.join(directory, entry, "SKILL.md")
+          next unless File.file?(skill_path)
+
+          paths[entry] = skill_path
+        end
+
+        new(paths)
+      end
+    end
+
+    #: (Hash[String, String] paths) -> void
+    def initialize(paths)
+      @paths = paths.freeze
+      # Deliberately mutable inside a frozen registry: `freeze` protects the set of skills, while
+      # the cache only remembers what was already read from those files.
+      @cache = {} #: Hash[String, Skill]
+      freeze
+    end
+
+    #: -> Array[String]
+    def ids
+      @paths.keys.sort
+    end
+
+    #: (String id) -> Rubydex::Skill
+    def fetch(id)
+      @cache[id] ||= begin
+        path = @paths[id]
+        raise UnknownSkillError, "Unknown skill: #{id}" unless path
+
+        skill = Skill.load(path)
+        unless skill.name == id
+          raise SkillError, "Skill in #{path} declares `name: #{skill.name}` but lives in `#{id}`"
+        end
+
+        skill
+      end
+    end
+  end
+end

data/lib/rubydex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubydex
-  VERSION = "0.3.0"
+  VERSION = "0.4.1"
 end

data/lib/rubydex.rb

@@ -2,8 +2,11 @@
 
 require "bundler"
 require "uri"
+
+# Files that must be loaded before the C extension
 require "rubydex/version"
 require "rubydex/mixin"
+require "rubydex/severity"
 
 begin
   # Load the precompiled version of the library
@@ -16,8 +19,11 @@ end
 
 require "rubydex/errors"
 require "rubydex/failures"
+require "rubydex/config"
 require "rubydex/location"
 require "rubydex/comment"
+require "rubydex/rule"
+require "rubydex/related_information"
 require "rubydex/diagnostic"
 require "rubydex/keyword"
 require "rubydex/keyword_parameter"
@@ -25,3 +31,5 @@ require "rubydex/graph"
 require "rubydex/declaration"
 require "rubydex/signature"
 require "rubydex/reference"
+
+Dir.glob("#{__dir__}/rubydex/rules/**/*.rb").each { |file| require file }

data/lib/rubydex_linter/rules/rule_structure.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module Linter
+    module Rules
+      # Ensures discovered workspace linter rules follow these conventions:
+      #
+      # - A rule file does not define more than one linter rule.
+      # - Each rule subclass outside a test directory is in a rule directory.
+      # - Each checked rule subclass is in the `Rubydex::Linter::Rules` namespace.
+      #
+      # The rule directories are `rubydex_linter/rules/` and `lib/rubydex_linter/rules/`, including
+      # `lib/rubydex_linter/rules/` directories in nested gems.
+      # This rule does not report files in those directories that define no rule subclass.
+      class RuleStructure < CustomRule
+        include Helpers::SourceAccessHelpers
+
+        BASE_RULE_NAME = "Rubydex::Linter::CustomRule" #: String
+        RULE_NAMESPACE = "Rubydex::Linter::Rules" #: String
+        RULE_FILE_PATTERNS = [
+          "rubydex_linter/rules/**/*.rb",
+          "**/lib/rubydex_linter/rules/**/*.rb",
+        ].freeze #: Array[String]
+        TEST_FILE_PATTERNS = ["test/**/*", "**/test/**/*"].freeze #: Array[String]
+
+        class << self
+          # @override
+          #: -> singleton(Severity::Base)
+          def default_severity
+            Severity::Error
+          end
+        end
+
+        # @override
+        #: -> void
+        def lint
+          rules = child_classes(BASE_RULE_NAME)
+          rule_definitions_by_file = {} #: Hash[String, Hash[Rubydex::Class, Definition]]
+
+          rules.each do |rule|
+            rule_docs = []
+
+            rule.definitions.each do |rule_definition|
+              uri = rule_definition.document.uri
+              path = path_for_uri(uri)
+              next unless path_in_workspace?(path)
+
+              if rule_file?(path)
+                rule_definitions = (rule_definitions_by_file[uri] ||= {}) #: Hash[Rubydex::Class, Definition]
+                rule_definitions[rule] ||= rule_definition
+              elsif !test_file?(path)
+                report_wrong_rule_directory(rule.name, rule_definition)
+              end
+
+              rule_docs.concat(rule_definition.comments)
+            end
+
+            rule_definition = rule.definitions.find do |definition|
+              path = path_for_uri(definition.document.uri)
+              path_in_workspace?(path) && (rule_file?(path) || !test_file?(path))
+            end
+            next unless rule_definition
+
+            rule_name = rule.name
+
+            if rule_docs.empty?
+              add_diagnostic(
+                "`#{rule_name}` is missing documentation.",
+                diagnostic_location(rule_definition),
+              )
+            end
+
+            next if rule_name.start_with?("#{RULE_NAMESPACE}::")
+
+            report_wrong_rule_namespace(rule_name, rule_definition)
+          end
+
+          rule_definitions_by_file.each do |uri, rule_definitions|
+            next if rule_definitions.length <= 1
+
+            add_diagnostic(
+              "Each rule file must define only one linter rule; found #{rule_definitions.length}.",
+              file_location(uri),
+              related_information: rule_definitions.map do |rule, rule_definition|
+                RelatedInformation.new(
+                  "`#{rule.name}` is defined here.",
+                  diagnostic_location(rule_definition),
+                )
+              end,
+            )
+          end
+        end
+
+        private
+
+        #: (String, Definition) -> void
+        def report_wrong_rule_directory(rule_name, rule_definition)
+          add_diagnostic(
+            "`#{rule_name}` must be defined under `rubydex_linter/rules/` or `lib/rubydex_linter/rules/`.",
+            diagnostic_location(rule_definition),
+          )
+        end
+
+        #: (String, Definition) -> void
+        def report_wrong_rule_namespace(rule_name, rule_definition)
+          add_diagnostic(
+            "`#{rule_name}` must be defined under `#{RULE_NAMESPACE}`.",
+            diagnostic_location(rule_definition),
+          )
+        end
+
+        #: (String) -> bool
+        def path_in_workspace?(path)
+          workspace = graph.workspace_path
+          path == workspace || path.start_with?("#{workspace}/")
+        end
+
+        #: (String) -> bool
+        def rule_file?(path)
+          path_matches_patterns?(path, RULE_FILE_PATTERNS)
+        end
+
+        #: (String) -> bool
+        def test_file?(path)
+          path_matches_patterns?(path, TEST_FILE_PATTERNS)
+        end
+
+        #: (String, Array[String]) -> bool
+        def path_matches_patterns?(path, patterns)
+          Helpers::PathHelpers.path_matches_patterns?(
+            path,
+            patterns,
+            workspace: graph.workspace_path,
+            flags: Helpers::PathHelpers::EXCLUDE_FNMATCH_FLAGS,
+          )
+        end
+      end
+    end
+  end
+end