rubyzen-lint 0.1.0

data/lib/rubyzen/declarations/constant_declaration.rb

@@ -0,0 +1,155 @@
+module Rubyzen
+  module Declarations
+    # Represents a constant assignment (+MAX = 100+) or reference (+MAX+).
+    #
+    # @example
+    #   const = file.constants.filter(&:assignment?).first
+    #   const.name        #=> "MAX"
+    #   const.value       #=> 100
+    #   const.top_level?  #=> true
+    #
+    class ConstantDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::ClassNameProvider
+      include Rubyzen::Providers::SourceCodeProvider
+
+      # @return [RuboCop::AST::Node]
+      attr_reader :node
+
+      # @return [FileDeclaration, ClassDeclaration, ModuleDeclaration]
+      attr_reader :parent
+
+      # @param node [RuboCop::AST::Node] the AST node
+      # @param parent [FileDeclaration, ClassDeclaration, ModuleDeclaration] the parent declaration
+      def initialize(node, parent)
+        @node = node
+        @parent = parent
+      end
+
+      # Returns the constant name.
+      #
+      # @return [String]
+      def name
+        case node.type
+        when :casgn
+          node.children[1].to_s
+        when :const
+          node.const_name
+        end
+      end
+
+      # Returns the assigned value for constant assignments.
+      #
+      # @return [String, Integer, Float, Boolean, nil]
+      def value
+        return nil unless assignment?
+
+        value_node = node.children[2]
+        return nil unless value_node
+
+        case value_node.type
+        when :str
+          value_node.str_content
+        when :int
+          value_node.children[0]
+        when :float
+          value_node.children[0]
+        when :true, :false
+          value_node.type == :true
+        else
+          value_node.source
+        end
+      end
+
+      # Returns whether this is a constant assignment (+:casgn+).
+      #
+      # @return [Boolean]
+      def assignment?
+        node.type == :casgn
+      end
+
+      # Returns whether this is a constant reference (+:const+).
+      #
+      # @return [Boolean]
+      def reference?
+        node.type == :const
+      end
+
+      # Returns whether this constant is defined at file scope (not inside a class or module).
+      #
+      # @return [Boolean]
+      def top_level?
+        return false unless parent.is_a?(Rubyzen::Declarations::FileDeclaration)
+
+        current_node = node
+        while current_node
+          current_node = current_node.parent
+          return false if current_node && (current_node.type == :class || current_node.type == :module)
+        end
+
+        true
+      end
+
+      # Returns the enclosing {ClassDeclaration}, if any.
+      #
+      # @return [ClassDeclaration, nil]
+      def enclosing_class
+        find_enclosing_ast_node(:class) do |n|
+          Rubyzen::Declarations::ClassDeclaration.new(n, file_declaration)
+        end
+      end
+
+      # Returns whether this constant is defined inside a class.
+      #
+      # @return [Boolean]
+      def in_class?
+        !enclosing_class.nil?
+      end
+
+      # Returns the enclosing {ModuleDeclaration}, if any.
+      #
+      # @return [ModuleDeclaration, nil]
+      def enclosing_module
+        find_enclosing_ast_node(:module) do |n|
+          Rubyzen::Declarations::ModuleDeclaration.new(n, file_declaration)
+        end
+      end
+
+      # Returns whether this constant is defined inside a module.
+      #
+      # @return [Boolean]
+      def in_module?
+        !enclosing_module.nil?
+      end
+
+      # Returns whether this constant is defined inside a class or module.
+      #
+      # @return [Boolean]
+      def scoped?
+        !top_level?
+      end
+
+      private
+
+      def file_declaration
+        current = parent
+        while current
+          return current if current.is_a?(Rubyzen::Declarations::FileDeclaration)
+          return current.file_declaration if current.respond_to?(:file_declaration)
+          current = current.respond_to?(:parent) ? current.parent : nil
+        end
+        nil
+      end
+
+      def find_enclosing_ast_node(type)
+        current_node = node.parent
+        while current_node
+          return yield(current_node) if current_node.type == type
+          current_node = current_node.respond_to?(:parent) ? current_node.parent : nil
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/rubyzen/declarations/file_declaration.rb

@@ -0,0 +1,69 @@
+module Rubyzen
+  module Declarations
+    # Represents a parsed Ruby source file. This is the root of the declaration
+    # hierarchy — all other declarations are accessed through a FileDeclaration.
+    #
+    # @example
+    #   project = Rubyzen::Project.new("/app/src")
+    #   file = project.files.first
+    #   file.name      #=> "user.rb"
+    #   file.classes   #=> [ClassDeclaration, ...]
+    #
+    class FileDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::LinesOfCodeProvider
+      include Rubyzen::Providers::ConstantsProvider
+      include Rubyzen::Providers::RequiresProvider
+      include Rubyzen::Providers::CallSiteProvider
+      include Rubyzen::Providers::BlocksProvider
+
+      # @return [String] absolute path to the source file
+      attr_reader :path
+
+      # @return [RuboCop::AST::Node] the root AST node
+      attr_reader :node
+      alias :ast :node
+
+      # @param path [String] absolute file path
+      # @param ast [RuboCop::AST::Node] parsed AST root node
+      def initialize(path, ast)
+        @path = path
+        @node = ast
+      end
+
+      # Returns the basename of the file.
+      #
+      # @return [String] e.g. +"user.rb"+
+      def name
+        File.basename(path)
+      end
+
+      # Returns all classes defined in this file.
+      #
+      # @return [Array<ClassDeclaration>]
+      def classes
+        node.each_node(:class).map do |class_node|
+          ClassDeclaration.new(class_node, self)
+        end
+      end
+
+      # Returns the name of the first module in the file, used to determine
+      # the top-level namespace.
+      #
+      # @return [String, nil]
+      def top_level_module_name
+        modules.first&.name_without_modules
+      end
+
+      # Returns all modules defined in this file.
+      #
+      # @return [Array<ModuleDeclaration>]
+      def modules
+        node.each_node(:module).map do |module_node|
+          Rubyzen::Declarations::ModuleDeclaration.new(module_node, self)
+        end
+      end
+    end
+  end
+end

data/lib/rubyzen/declarations/if_statement_declaration.rb

@@ -0,0 +1,44 @@
+module Rubyzen
+  module Declarations
+    # Represents an +if+ / +unless+ statement within a method or class.
+    #
+    # @example
+    #   if_stmt = method.if_statements.first
+    #   if_stmt.condition_source #=> "user.active?"
+    #   if_stmt.source_code      #=> "if user.active?\n  ..."
+    #
+    class IfStatementDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::ClassNameProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::SourceCodeProvider
+
+      # @return [RuboCop::AST::Node]
+      attr_reader :node
+
+      # @return [MethodDeclaration, ClassDeclaration]
+      attr_reader :parent
+
+      # @param node [RuboCop::AST::Node] the AST node
+      # @param parent [MethodDeclaration, ClassDeclaration] the parent declaration
+      def initialize(node, parent)
+        @node = node
+        @parent = parent
+      end
+
+      # Returns the raw source of the condition expression.
+      #
+      # @return [String, nil]
+      def condition_source
+        node.condition&.source
+      end
+
+      # Returns the name of the parent declaration.
+      #
+      # @return [String]
+      def name
+        parent.name
+      end
+    end
+  end
+end

data/lib/rubyzen/declarations/macro_declaration.rb

@@ -0,0 +1,81 @@
+module Rubyzen
+  module Declarations
+    # Represents a class-level macro call (e.g. +validates_required+, +belongs_to+).
+    #
+    # @example
+    #   macro = klass.macros.first
+    #   macro.name          #=> "validates_required"
+    #   macro.symbols       #=> [:name, :email]
+    #   macro.keyword_args  #=> [:foreign_key, :optional]
+    #
+    class MacroDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::ClassNameProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::SourceCodeProvider
+
+      # @return [RuboCop::AST::Node]
+      attr_reader :node
+
+      # @return [ClassDeclaration]
+      attr_reader :parent
+
+      # @param node [RuboCop::AST::Node] the AST node
+      # @param parent [ClassDeclaration] the parent declaration
+      def initialize(node, parent)
+        @node = node
+        @parent = parent
+      end
+
+      # Returns the macro method name.
+      #
+      # @return [String] e.g. +"validates_required"+, +"belongs_to"+
+      def name
+        node.method_name.to_s
+      end
+
+      # Returns positional symbol arguments.
+      #
+      # @return [Array<Symbol>]
+      def symbols
+        node.arguments.select { |arg| arg.type == :sym }.map(&:value)
+      end
+
+      # Returns positional string arguments.
+      #
+      # @return [Array<String>]
+      def strings
+        node.arguments.select { |arg| arg.type == :str }.map(&:value)
+      end
+
+      # Returns keyword argument keys.
+      #
+      # @return [Array<Symbol>]
+      def keyword_args
+        extract_keyword_args(node)
+      end
+
+      # Returns the constant receiver, if any.
+      #
+      # @return [String, nil] e.g. +"Config"+ for +Config.setting+
+      def receiver
+        node.receiver&.type == :const ? node.receiver.const_name : nil
+      end
+
+      private
+
+      def extract_keyword_args(send_node)
+        send_node.arguments.flat_map do |arg|
+          if arg.hash_type?
+            arg.each_pair.map do |pair|
+              key_node = pair.key
+              key_node.type == :sym ? key_node.value : nil
+            end.compact
+          else
+            []
+          end
+        end.uniq
+      end
+    end
+  end
+end

data/lib/rubyzen/declarations/method_declaration.rb

@@ -0,0 +1,63 @@
+module Rubyzen
+  module Declarations
+    # Represents a Ruby method definition (+def+ or +def self.+).
+    #
+    # @example
+    #   method = klass.instance_methods.first
+    #   method.name          #=> "calculate"
+    #   method.parameters?   #=> true
+    #   method.call_sites    #=> CallSiteCollection
+    #   method.visibility    #=> :private
+    #
+    class MethodDeclaration
+      include Rubyzen::Providers::IfStatementsProvider
+      include Rubyzen::Providers::BlocksProvider
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::ClassNameProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::ConstantsProvider
+      include Rubyzen::Providers::CallSiteProvider
+      include Rubyzen::Providers::LinesOfCodeProvider
+      include Rubyzen::Providers::VisibilityProvider
+      include Rubyzen::Providers::RescuesProvider
+      include Rubyzen::Providers::RaisesProvider
+
+      # @return [RuboCop::AST::Node]
+      attr_reader :node
+
+      # @return [ClassDeclaration, ModuleDeclaration]
+      attr_reader :parent_class
+      alias :parent :parent_class
+
+      def initialize(node, parent_class)
+        @node = node
+        @parent_class = parent_class
+      end
+
+      # Returns the method name.
+      #
+      # @return [String]
+      def name
+        node.method_name.to_s
+      end
+
+      # Returns the method's parameters.
+      #
+      # @return [Collections::ParametersCollection]
+      def parameters
+        Collections::ParametersCollection.new(
+          node.arguments.map do |arg|
+            ParameterDeclaration.new(arg, self)
+          end
+        )
+      end
+
+      # Returns whether this method has any parameters.
+      #
+      # @return [Boolean]
+      def parameters?
+        node.arguments.any?
+      end
+    end
+  end
+end

data/lib/rubyzen/declarations/module_declaration.rb

@@ -0,0 +1,115 @@
+module Rubyzen
+  module Declarations
+    # Represents a Ruby module definition.
+    #
+    # @example
+    #   mod = file.modules.first
+    #   mod.name           #=> "Admin::Api"
+    #   mod.all_methods    #=> MethodsCollection
+    #   mod.classes        #=> [ClassDeclaration, ...]
+    #
+    class ModuleDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::ClassNameProvider
+      include Rubyzen::Providers::ConstantsProvider
+      include Rubyzen::Providers::LinesOfCodeProvider
+      include Rubyzen::Providers::AttributesProvider
+
+      # @return [RuboCop::AST::Node]
+      attr_reader :node
+
+      # @return [FileDeclaration]
+      attr_reader :file_declaration
+
+      # @param node [RuboCop::AST::Node] the AST node
+      # @param file_declaration [FileDeclaration] the parent file declaration
+      def initialize(node, file_declaration)
+        @node = node
+        @file_declaration = file_declaration
+      end
+
+      # Returns the fully-qualified module name including parent modules.
+      #
+      # @return [String] e.g. +"Admin::Api"+
+      def name
+        parent_module_names = []
+        current_node = node.parent
+
+        while current_node
+          if current_node.type == :module
+            parent_module_names.unshift(current_node.identifier&.const_name)
+          end
+          current_node = current_node.parent
+        end
+
+        [parent_module_names, name_without_modules].flatten.compact.join('::')
+      end
+
+      # Returns the module name without parent module prefixes.
+      #
+      # @return [String]
+      def name_without_modules
+        node.identifier&.const_name
+      end
+
+      # Returns nested modules within this module.
+      #
+      # @return [Array<ModuleDeclaration>]
+      def modules
+        node.each_descendant(:module).map { |mod_node| ModuleDeclaration.new(mod_node, file_declaration) }
+      end
+
+      # Returns classes defined within this module.
+      #
+      # @return [Array<ClassDeclaration>]
+      def classes
+        node.each_node(:class).map do |class_node|
+          ClassDeclaration.new(class_node, file_declaration)
+        end
+      end
+
+      # Returns methods defined directly in this module.
+      #
+      # @return [Collections::MethodsCollection]
+      def all_methods
+        Collections::MethodsCollection.new(
+          direct_method_nodes.map { |method_node| MethodDeclaration.new(method_node, self) }
+        )
+      end
+
+      private
+
+      def module_body_node
+        node.children[1]
+      end
+
+      def module_body_children
+        body = module_body_node
+        return [] unless body
+
+        body.type == :begin ? body.child_nodes : [body]
+      end
+
+      def direct_method_nodes
+        direct_nodes = module_body_children.select do |child|
+          %i[def defs].include?(child.type)
+        end
+        singleton_nodes = module_body_children.flat_map do |child|
+          next [] unless child.type == :sclass
+          next [] unless child.children[0]&.type == :self
+
+          sclass_body = child.children[1]
+          next [] unless sclass_body
+
+          sclass_children = sclass_body.type == :begin ? sclass_body.child_nodes : [sclass_body]
+          sclass_children.select do |sclass_child|
+            %i[def defs].include?(sclass_child.type)
+          end
+        end
+
+        direct_nodes + singleton_nodes
+      end
+    end
+  end
+end

data/lib/rubyzen/declarations/parameter_declaration.rb

@@ -0,0 +1,43 @@
+module Rubyzen
+  module Declarations
+    # Represents a method parameter.
+    #
+    # @example
+    #   param = method.parameters.first
+    #   param.name           #=> :user_id
+    #   param.default_value  #=> 42
+    #
+    class ParameterDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::ClassNameProvider
+
+      # @return [RuboCop::AST::Node]
+      attr_reader :node
+
+      # @return [MethodDeclaration]
+      attr_reader :parent
+
+      # @param node [RuboCop::AST::Node] the AST node
+      # @param parent [MethodDeclaration] the parent declaration
+      def initialize(node, parent)
+        @node = node
+        @parent = parent
+      end
+
+      # Returns the parameter name.
+      #
+      # @return [Symbol]
+      def name
+        node.name
+      end
+
+      # Returns the default value if one is defined.
+      #
+      # @return [Object, nil]
+      def default_value
+        node.children[1]&.value
+      end
+    end
+  end
+end

data/lib/rubyzen/declarations/raise_declaration.rb

@@ -0,0 +1,87 @@
+module Rubyzen
+  module Declarations
+    # Represents a +raise+ statement.
+    #
+    # @example
+    #   raise_decl = method.raises.first
+    #   raise_decl.exception_types #=> ["ArgumentError"]
+    #   raise_decl.message         #=> "invalid input"
+    #   raise_decl.with_string?    #=> false
+    #
+    class RaiseDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::ClassNameProvider
+      include Rubyzen::Providers::SourceCodeProvider
+
+      # @return [RuboCop::AST::Node]
+      attr_reader :node
+
+      # @return [MethodDeclaration, BlockDeclaration]
+      attr_reader :parent
+
+      # @param node [RuboCop::AST::Node] the AST node
+      # @param parent [MethodDeclaration, BlockDeclaration] the parent declaration
+      def initialize(node, parent)
+        @node = node
+        @parent = parent
+      end
+
+      # Returns the exception class names being raised.
+      # Defaults to +["RuntimeError"]+ for bare +raise+ or +raise "message"+.
+      #
+      # @return [Array<String>]
+      def exception_types
+        extract_exception_types
+      end
+
+      # Returns whether the raise uses a bare string (+raise "message"+).
+      #
+      # @return [Boolean]
+      def with_string?
+        first_arg = node.arguments.first
+        first_arg&.type == :str
+      end
+
+      # Returns the error message string, if any.
+      #
+      # @return [String, nil]
+      def message
+        extract_message
+      end
+
+      private
+
+      def extract_exception_types
+        first_arg = node.arguments.first
+
+        return ['RuntimeError'] if first_arg.nil? || first_arg.type == :str
+
+        if first_arg.type == :const
+          [first_arg.const_name]
+        elsif first_arg.type == :send && first_arg.method_name == :new
+          receiver = first_arg.receiver
+          receiver&.type == :const ? [receiver.const_name] : ['RuntimeError']
+        else
+          ['RuntimeError']
+        end
+      end
+
+      def extract_message
+        first_arg = node.arguments.first
+        second_arg = node.arguments[1]
+
+        if first_arg&.type == :str
+          first_arg.value
+        elsif second_arg&.type == :str
+          second_arg.value
+        elsif first_arg&.type == :send && first_arg.method_name == :new
+          msg_arg = first_arg.arguments.first
+          msg_arg&.type == :str ? msg_arg.value : nil
+        else
+          nil
+        end
+      end
+    end
+  end
+end