rubydex 0.4.0 → 0.4.1

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/skill.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "yaml"
 require "rubydex/errors"
 
 module Rubydex

data/lib/rubydex/version.rb

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

data/lib/rubydex.rb

@@ -31,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

@@ -9,7 +9,8 @@ module Rubydex
       # - 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/`.
+      # 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
@@ -18,7 +19,7 @@ module Rubydex
         RULE_NAMESPACE = "Rubydex::Linter::Rules" #: String
         RULE_FILE_PATTERNS = [
           "rubydex_linter/rules/**/*.rb",
-          "lib/rubydex_linter/rules/**/*.rb",
+          "**/lib/rubydex_linter/rules/**/*.rb",
         ].freeze #: Array[String]
         TEST_FILE_PATTERNS = ["test/**/*", "**/test/**/*"].freeze #: Array[String]
 
@@ -37,6 +38,8 @@ module Rubydex
           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)
@@ -48,6 +51,8 @@ module Rubydex
               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|
@@ -55,9 +60,19 @@ module Rubydex
               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)
+            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|

data/rbi/rubydex.rbi

@@ -175,8 +175,17 @@ class Rubydex::AttrAccessorDefinition < Rubydex::Definition; end
 class Rubydex::AttrReaderDefinition < Rubydex::Definition; end
 class Rubydex::AttrWriterDefinition < Rubydex::Definition; end
 class Rubydex::ClassVariableDefinition < Rubydex::Definition; end
-class Rubydex::ConstantAliasDefinition < Rubydex::Definition; end
-class Rubydex::ConstantDefinition < Rubydex::Definition; end
+
+class Rubydex::ConstantAliasDefinition < Rubydex::Definition
+  sig { returns(String) }
+  def raw_name; end
+end
+
+class Rubydex::ConstantDefinition < Rubydex::Definition
+  sig { returns(String) }
+  def raw_name; end
+end
+
 class Rubydex::GlobalVariableAliasDefinition < Rubydex::Definition; end
 class Rubydex::GlobalVariableDefinition < Rubydex::Definition; end
 class Rubydex::InstanceVariableDefinition < Rubydex::Definition; end
@@ -271,6 +280,9 @@ class Rubydex::Signature::BlockParameter < Rubydex::Signature::Parameter; end
 class Rubydex::ModuleDefinition < Rubydex::Definition
   sig { returns(T::Array[Rubydex::Mixin]) }
   def mixins; end
+
+  sig { returns(String) }
+  def raw_name; end
 end
 
 class Rubydex::SingletonClassDefinition < Rubydex::Definition
@@ -284,6 +296,9 @@ class Rubydex::ClassDefinition < Rubydex::Definition
 
   sig { returns(T::Array[Rubydex::Mixin]) }
   def mixins; end
+
+  sig { returns(String) }
+  def raw_name; end
 end
 
 class Rubydex::Mixin
@@ -337,80 +352,6 @@ class Rubydex::Rule
   end
 end
 
-module Rubydex::Rules
-  ALL = T.let(T.unsafe(nil), T::Array[T.class_of(Rubydex::Rule)])
-end
-
-class Rubydex::Rules::ParseError < Rubydex::Rule
-  class << self
-    sig { override.returns(T.class_of(Rubydex::Severity::Base)) }
-    def default_severity; end
-  end
-end
-
-class Rubydex::Rules::ParseWarning < Rubydex::Rule
-  class << self
-    sig { override.returns(T.class_of(Rubydex::Severity::Base)) }
-    def default_severity; end
-  end
-end
-
-class Rubydex::Rules::DynamicConstantReference < Rubydex::Rule
-  class << self
-    sig { override.returns(T.class_of(Rubydex::Severity::Base)) }
-    def default_severity; end
-  end
-end
-
-class Rubydex::Rules::DynamicSingletonDefinition < Rubydex::Rule
-  class << self
-    sig { override.returns(T.class_of(Rubydex::Severity::Base)) }
-    def default_severity; end
-  end
-end
-
-class Rubydex::Rules::DynamicAncestor < Rubydex::Rule
-  class << self
-    sig { override.returns(T.class_of(Rubydex::Severity::Base)) }
-    def default_severity; end
-  end
-end
-
-class Rubydex::Rules::TopLevelMixinSelf < Rubydex::Rule
-  class << self
-    sig { override.returns(T.class_of(Rubydex::Severity::Base)) }
-    def default_severity; end
-  end
-end
-
-class Rubydex::Rules::InvalidConstantVisibility < Rubydex::Rule
-  class << self
-    sig { override.returns(T.class_of(Rubydex::Severity::Base)) }
-    def default_severity; end
-  end
-end
-
-class Rubydex::Rules::InvalidMethodVisibility < Rubydex::Rule
-  class << self
-    sig { override.returns(T.class_of(Rubydex::Severity::Base)) }
-    def default_severity; end
-  end
-end
-
-class Rubydex::Rules::UndefinedMethodVisibilityTarget < Rubydex::Rule
-  class << self
-    sig { override.returns(T.class_of(Rubydex::Severity::Base)) }
-    def default_severity; end
-  end
-end
-
-class Rubydex::Rules::UndefinedConstantVisibilityTarget < Rubydex::Rule
-  class << self
-    sig { override.returns(T.class_of(Rubydex::Severity::Base)) }
-    def default_severity; end
-  end
-end
-
 class Rubydex::RelatedInformation
   sig { params(message: String, location: Rubydex::Location).void }
   def initialize(message, location); end
@@ -594,58 +535,6 @@ class Rubydex::Linter::Rules::RuleStructure < Rubydex::Linter::CustomRule
   def lint; end
 end
 
-class Rubydex::Linter::RuleTestCase < Minitest::Test
-  DEFAULT_FILE = T.let(T.unsafe(nil), String)
-  ANNOTATION_PATTERN = T.let(T.unsafe(nil), Regexp)
-
-  sig { returns(String) }
-  def workspace_path; end
-
-  sig { params(name: String).void }
-  def initialize(name); end
-
-  sig { void }
-  def teardown; end
-
-  sig { returns(T.class_of(Rubydex::Linter::CustomRule)) }
-  def rule_class; end
-
-  sig { params(sources: T::Hash[String, String]).void }
-  def add_shared_source(sources); end
-
-  sig { returns(T::Array[String]) }
-  def ignored_diagnostic_files; end
-
-  sig { returns(Rubydex::LinterConfig) }
-  def rule_config; end
-
-  sig do
-    params(
-      args: T.any(String, T::Hash[T.any(String, Symbol), String]),
-      rule_builder: T.nilable(T.proc.params(graph: Rubydex::Graph).returns(Rubydex::Linter::CustomRule)),
-    ).returns(T::Array[Rubydex::Diagnostic])
-  end
-  def assert_diagnostics(*args, &rule_builder); end
-
-  sig do
-    params(
-      args: T.any(String, T::Hash[T.any(String, Symbol), String]),
-      rule_builder: T.nilable(T.proc.params(graph: Rubydex::Graph).returns(Rubydex::Linter::CustomRule)),
-    ).returns(T::Array[Rubydex::Diagnostic])
-  end
-  def assert_no_diagnostics(*args, &rule_builder); end
-
-  sig do
-    params(
-      dependency: String,
-      args: T.any(String, T::Hash[T.any(String, Symbol), String]),
-      after_excluding: T::Array[String],
-      rule_builder: T.nilable(T.proc.params(graph: Rubydex::Graph).returns(Rubydex::Linter::CustomRule)),
-    ).void
-  end
-  def assert_handles_missing_required_dependency(dependency, *args, after_excluding: [], &rule_builder); end
-end
-
 class Rubydex::Linter::Runner
   sig do
     params(
@@ -891,8 +780,18 @@ class Rubydex::Graph
   sig { returns(T.self_type) }
   def resolve; end
 
-  sig { params(name: String, nesting: T::Array[String]).returns(T.nilable(Rubydex::Declaration)) }
-  def resolve_constant(name, nesting); end
+  sig do
+    params(
+      name: String,
+      context: T.any(
+        T::Array[String],
+        Rubydex::ClassDefinition,
+        Rubydex::SingletonClassDefinition,
+        Rubydex::ModuleDefinition,
+      ),
+    ).returns(T.nilable(Rubydex::Declaration))
+  end
+  def resolve_constant(name, context); end
 
   sig { params(require_path: String, load_paths: T::Array[String]).returns(T.nilable(Rubydex::Document)) }
   def resolve_require_path(require_path, load_paths); end
@@ -903,6 +802,9 @@ class Rubydex::Graph
   sig { params(queries: String).returns(T::Enumerable[Rubydex::Declaration]) }
   def fuzzy_search(*queries); end
 
+  sig { returns(T::Enumerable[Rubydex::Declaration]) }
+  def dead_code_candidates; end
+
   sig { params(encoding: String).void }
   def encoding=(encoding); end
 

data/rust/rubydex/Cargo.toml

@@ -15,6 +15,10 @@ categories = ["development-tools"]
 name = "rubydex_cli"
 path = "src/main.rs"
 
+[[bin]]
+name = "generate_ruby_rules"
+path = "src/bin/generate_ruby_rules.rs"
+
 [lib]
 crate-type = ["rlib"]
 

data/rust/rubydex/src/bin/generate_ruby_rules.rs

@@ -0,0 +1,94 @@
+use rubydex::diagnostic::{Rule, Severity};
+use std::collections::HashSet;
+use std::path::Path;
+use std::{env, fs};
+
+// Takes the built-in diagnostic rules and generates Ruby classes for them in `lib/rubydex/rules`.
+fn main() {
+    let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("..").join("..");
+    let directory = root.join("lib").join("rubydex").join("rules");
+    let mut generated_files = HashSet::new();
+
+    for rule in Rule::all().iter().copied() {
+        write_rule(&directory, rule, &mut generated_files);
+    }
+
+    // Remove stale rules
+    for entry in fs::read_dir(&directory).unwrap() {
+        let entry = entry.unwrap();
+        let path = entry.path();
+
+        if path.is_file() {
+            let file_name = path.file_name().unwrap().to_string_lossy();
+
+            if !generated_files.contains(&file_name.to_string()) {
+                fs::remove_file(path).unwrap();
+            }
+        }
+    }
+}
+
+fn write_rule(dir: &Path, rule: Rule, generated_files: &mut HashSet<String>) {
+    let documentation = rule
+        .documentation()
+        .iter()
+        .map(|line| format!("    #{line}").trim_end().to_owned())
+        .collect::<Vec<String>>()
+        .join("\n");
+
+    let contents = format!(
+        "# typed: strict
+# frozen_string_literal: true
+
+# This file is generated by `generate_ruby_rules.rs`. Do not edit this manually.
+
+module Rubydex
+  module Rules
+{documentation}
+    class {name} < Rule
+      class << self
+        # @override
+        #: -> singleton(Severity::Base)
+        def default_severity
+          {severity}
+        end
+      end
+    end
+  end
+end
+",
+        name = rule.name(),
+        severity = to_ruby_severity(rule.default_severity()),
+    );
+
+    let file_name = format!("{}.rb", snake_case(rule.name()));
+    fs::write(dir.join(&file_name), contents).unwrap();
+    generated_files.insert(file_name);
+}
+
+fn to_ruby_severity(severity: Severity) -> &'static str {
+    match severity {
+        Severity::Error => "Severity::Error",
+        Severity::Warning => "Severity::Warning",
+        Severity::Information => "Severity::Information",
+        Severity::Hint => "Severity::Hint",
+    }
+}
+
+fn snake_case(name: &str) -> String {
+    let mut result = String::with_capacity(name.len() + 4);
+
+    for (index, character) in name.char_indices() {
+        if character.is_uppercase() {
+            if index != 0 {
+                result.push('_');
+            }
+
+            result.extend(character.to_lowercase());
+        } else {
+            result.push(character);
+        }
+    }
+
+    result
+}

data/rust/rubydex/src/diagnostic.rs

@@ -64,10 +64,10 @@ pub enum Severity {
 }
 
 macro_rules! rules {
-    ($($(#[$attribute:meta])* $rule:ident),+ $(,)?) => {
+    ($($(#[doc = $documentation:literal])+ $rule:ident => $severity:ident),+ $(,)?) => {
         #[derive(Debug, Copy, Clone, PartialEq, Eq)]
         pub enum Rule {
-            $($(#[$attribute])* $rule,)+
+            $($(#[doc = $documentation])+ $rule,)+
         }
 
         impl Rule {
@@ -75,60 +75,151 @@ macro_rules! rules {
             pub fn all() -> &'static [Self] {
                 &[$(Self::$rule,)+]
             }
+
+            #[must_use]
+            pub fn name(&self) -> &'static str {
+                match self {
+                    $(Self::$rule => stringify!($rule),)+
+                }
+            }
+
+            #[must_use]
+            pub fn default_severity(&self) -> Severity {
+                match self {
+                    $(Self::$rule => Severity::$severity,)+
+                }
+            }
+
+            #[must_use]
+            pub fn documentation(&self) -> &'static [&'static str] {
+                match self {
+                    $(Self::$rule => &[$($documentation,)+],)+
+                }
+            }
         }
     };
 }
 
 rules! {
-    // Parsing
-    ParseError,
-    ParseWarning,
-
-    // Indexing
-    DynamicConstantReference,
-    DynamicSingletonDefinition,
-    DynamicAncestor,
-    TopLevelMixinSelf,
-    InvalidConstantVisibility,
-    InvalidMethodVisibility,
-
-    // Resolution
-    UndefinedMethodVisibilityTarget,
-    UndefinedConstantVisibilityTarget,
-}
-
-impl Rule {
-    #[must_use]
-    pub fn name(&self) -> &'static str {
-        match self {
-            Self::ParseError => "ParseError",
-            Self::ParseWarning => "ParseWarning",
-            Self::DynamicConstantReference => "DynamicConstantReference",
-            Self::DynamicSingletonDefinition => "DynamicSingletonDefinition",
-            Self::DynamicAncestor => "DynamicAncestor",
-            Self::TopLevelMixinSelf => "TopLevelMixinSelf",
-            Self::InvalidConstantVisibility => "InvalidConstantVisibility",
-            Self::InvalidMethodVisibility => "InvalidMethodVisibility",
-            Self::UndefinedMethodVisibilityTarget => "UndefinedMethodVisibilityTarget",
-            Self::UndefinedConstantVisibilityTarget => "UndefinedConstantVisibilityTarget",
-        }
-    }
-
-    #[must_use]
-    pub fn default_severity(&self) -> Severity {
-        match self {
-            Self::ParseError => Severity::Error,
-            Self::ParseWarning
-            | Self::InvalidConstantVisibility
-            | Self::InvalidMethodVisibility
-            | Self::UndefinedMethodVisibilityTarget
-            | Self::UndefinedConstantVisibilityTarget => Severity::Warning,
-            Self::DynamicConstantReference
-            | Self::DynamicSingletonDefinition
-            | Self::DynamicAncestor
-            | Self::TopLevelMixinSelf => Severity::Information,
-        }
-    }
+    // ******** Parsing ******** //
+
+    /// 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
+    /// ```
+    ParseError => Error,
+
+    /// 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
+    /// ```
+    ParseWarning => Warning,
+
+    // ******** Indexing ******** //
+
+    /// Dynamic constant references 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::Foo
+    /// ^^^^^^^^ Dynamic constant reference. This might be correct, but it cannot be understood by the analysis.
+    /// ```
+    DynamicConstantReference => Information,
+
+    /// Dynamic singleton targets 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
+    /// class << var
+    ///          ^^^ Dynamic singleton target. This might be correct, but it cannot be understood by the analysis.
+    /// end
+    ///
+    /// def var.bar
+    ///     ^^^ Dynamic singleton target.
+    /// end
+    /// ```
+    DynamicSingletonDefinition => Information,
+
+    /// Dynamic ancestor references cannot be reasoned about statically because they depend on runtime values. The
+    /// program may still be valid, but the quality of the analysis degrades. In the case of ancestors, since they
+    /// influence constant resolution, the degradation may be more impactful than other dynamic references.
+    ///
+    /// ```ruby
+    /// class Foo < var
+    ///             ^^^ Dynamic ancestor reference. This might be correct, but it cannot be understood by the analysis.
+    ///   include SomeClass.method_call
+    ///           ^^^^^^^^^^^^^^^^^^^^^ Dynamic ancestor reference.
+    /// end
+    /// ```
+    DynamicAncestor => Information,
+
+    /// 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
+    /// ```
+    TopLevelMixinSelf => Information,
+
+    /// Constant 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_constant :Foo
+    /// ^^^ Invalid constant visibility. This might be correct, but it cannot be understood by the analysis.
+    ///
+    /// private_constant(var)
+    ///                  ^^^ Invalid constant visibility.
+    /// ```
+    InvalidConstantVisibility => Warning,
+
+    /// 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.
+    /// ```
+    InvalidMethodVisibility => Warning,
+
+    // ******** Resolution ******** //
+
+    /// 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
+    /// ```
+    UndefinedMethodVisibilityTarget => Warning,
+
+    /// 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
+    /// ```
+    UndefinedConstantVisibilityTarget => Warning,
 }
 
 impl std::fmt::Display for Rule {