rubydex 0.2.9 → 0.4.0

data/lib/rubydex/skill.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+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.2.9"
+  VERSION = "0.4.0"
 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"

data/lib/rubydex_linter/rules/rule_structure.rb

@@ -0,0 +1,125 @@
+# 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/`.
+      # 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.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
+            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
+            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