rubyzen-lint 0.1.0

data/lib/rubyzen/collections/file_collection.rb

@@ -0,0 +1,81 @@
+
+module Rubyzen
+  module Collections
+    # Collection of parsed file declarations. Serves as the top-level entry point
+    # for navigating into classes, modules, constants, and other code elements.
+    #
+    # @example Getting all controller classes
+    #   project.files.with_paths('src/controllers/').classes
+    class FileCollection < BaseCollection
+      include Rubyzen::Providers::CollectionFilterProvider
+
+      # Filters files whose path includes any of the given substrings.
+      #
+      # @param paths [Array<String>] path substrings to match
+      # @return [FileCollection]
+      def with_paths(*paths)
+        filter do |file_declaration|
+          paths.any? { |p| file_declaration.path.include?(p) }
+        end
+      end
+
+      # Excludes files whose path includes any of the given substrings.
+      #
+      # @param paths [Array<String>] path substrings to exclude
+      # @return [FileCollection]
+      def without_paths(*paths)
+        filter do |file_declaration|
+          !paths.any? { |p| file_declaration.path.include?(p) }
+        end
+      end
+
+      # Returns all class declarations across every file.
+      #
+      # @return [ClassesCollection]
+      def classes
+        all_classes = flat_map(&:classes)
+        ClassesCollection.new(all_classes)
+      end
+
+      # Returns all module declarations across every file.
+      #
+      # @return [ModulesCollection]
+      def modules
+        all_modules = flat_map(&:modules)
+        ModulesCollection.new(all_modules)
+      end
+
+      # Returns all constant declarations across every file.
+      #
+      # @return [ConstantsCollection]
+      def constants
+        all_constants = flat_map(&:constants)
+        ConstantsCollection.new(all_constants)
+      end
+
+      # Returns all require/require_relative/load statements across every file.
+      #
+      # @return [RequiresCollection]
+      def requires
+        all_requires = flat_map(&:requires)
+        RequiresCollection.new(all_requires)
+      end
+
+      # Returns all call sites across every file.
+      #
+      # @return [CallSiteCollection]
+      def call_sites
+        all_call_sites = flat_map(&:call_sites)
+        CallSiteCollection.new(all_call_sites)
+      end
+
+      # Returns all block declarations across every file.
+      #
+      # @return [BlocksCollection]
+      def blocks
+        all_blocks = flat_map(&:blocks)
+        BlocksCollection.new(all_blocks)
+      end
+    end
+  end
+end

data/lib/rubyzen/collections/macros_collection.rb

@@ -0,0 +1,11 @@
+module Rubyzen
+  module Collections
+    # Collection of class-level macro invocations (e.g., +validates+, +has_many+, +before_action+).
+    #
+    # @example Filtering macros by name
+    #   controllers.macros.with_name('before_action')
+    class MacrosCollection < BaseCollection
+      include Rubyzen::Providers::CollectionFilterProvider
+    end
+  end
+end

data/lib/rubyzen/collections/methods_collection.rb

@@ -0,0 +1,67 @@
+module Rubyzen
+  module Collections
+    # Collection of method declarations with access to parameters,
+    # call sites, if statements, rescues, and raises within each method.
+    #
+    # @example Ensuring no method has more than 5 parameters
+    #   controllers.all_methods.each { |m| expect(m.parameters.size).to be <= 5 }
+    class MethodsCollection < BaseCollection
+      include Rubyzen::Providers::CollectionFilterProvider
+
+      # Returns all parameters across every method.
+      #
+      # @return [ParametersCollection]
+      def parameters
+        ParametersCollection.new(
+          flat_map do |method|
+            method.parameters
+          end
+        )
+      end
+
+      # Returns all if-statement declarations across every method.
+      #
+      # @return [DeclarationCollection]
+      def if_statements
+        DeclarationCollection.new(
+          flat_map do |method|
+            method.if_statements
+          end
+        )
+      end
+
+      # Returns all call sites across every method.
+      #
+      # @return [CallSiteCollection]
+      def call_sites
+        CallSiteCollection.new(
+          flat_map do |method|
+            method.call_sites
+          end
+        )
+      end
+
+      # Returns all rescue declarations across every method.
+      #
+      # @return [RescuesCollection]
+      def rescues
+        RescuesCollection.new(
+          flat_map do |method|
+            method.rescues
+          end
+        )
+      end
+
+      # Returns all raise declarations across every method.
+      #
+      # @return [RaisesCollection]
+      def raises
+        RaisesCollection.new(
+          flat_map do |method|
+            method.raises
+          end
+        )
+      end
+    end
+  end
+end

data/lib/rubyzen/collections/modules_collection.rb

@@ -0,0 +1,36 @@
+module Rubyzen
+  module Collections
+    # Collection of module declarations with methods for navigating into
+    # child elements (methods, classes, constants).
+    #
+    # @example Getting all methods defined in modules
+    #   project.files.modules.all_methods
+    class ModulesCollection < BaseCollection
+      include Rubyzen::Providers::CollectionFilterProvider
+
+      # Returns all methods defined across every module.
+      #
+      # @return [MethodsCollection]
+      def all_methods
+        all_methods = flat_map(&:all_methods)
+        MethodsCollection.new(all_methods)
+      end
+
+      # Returns all class declarations nested inside every module.
+      #
+      # @return [ClassesCollection]
+      def classes
+        all_classes = flat_map(&:classes)
+        ClassesCollection.new(all_classes)
+      end
+
+      # Returns all constant declarations across every module.
+      #
+      # @return [ConstantsCollection]
+      def constants
+        all_constants = flat_map(&:constants)
+        ConstantsCollection.new(all_constants)
+      end
+    end
+  end
+end

data/lib/rubyzen/collections/parameters_collection.rb

@@ -0,0 +1,11 @@
+module Rubyzen
+  module Collections
+    # Collection of method parameter declarations.
+    #
+    # @example Filtering parameters by name
+    #   controllers.all_methods.parameters.with_name('id')
+    class ParametersCollection < BaseCollection
+      include Rubyzen::Providers::CollectionFilterProvider
+    end
+  end
+end

data/lib/rubyzen/collections/raises_collection.rb

@@ -0,0 +1,26 @@
+module Rubyzen
+  module Collections
+    # Collection of raise declarations found in methods or classes.
+    #
+    # @example Ensuring no plain-string raises in controllers
+    #   expect(controllers.raises.with_string).to zen_empty
+    class RaisesCollection < BaseCollection
+      # Filters raises that use a plain string message (not an exception class).
+      #
+      # @return [RaisesCollection]
+      def with_string
+        filter(&:with_string?)
+      end
+
+      # Filters raises that include the given exception class.
+      #
+      # @param exception_class [String] the exception class name to match
+      # @return [RaisesCollection]
+      def with_exception_type(exception_class)
+        filter do |raise_declaration|
+          raise_declaration.exception_types.include?(exception_class)
+        end
+      end
+    end
+  end
+end

data/lib/rubyzen/collections/requires_collection.rb

@@ -0,0 +1,32 @@
+module Rubyzen
+  module Collections
+    # Collection of require/require_relative/load statements found in files.
+    #
+    # @example Ensuring controllers do not use require_relative
+    #   expect(controller_files.requires.require_relative_calls).to zen_empty
+    class RequiresCollection < BaseCollection
+      include Rubyzen::Providers::CollectionFilterProvider
+
+      # Returns only +require+ calls.
+      #
+      # @return [RequiresCollection]
+      def require_calls
+        filter(&:require?)
+      end
+
+      # Returns only +require_relative+ calls.
+      #
+      # @return [RequiresCollection]
+      def require_relative_calls
+        filter(&:require_relative?)
+      end
+
+      # Returns only +load+ calls.
+      #
+      # @return [RequiresCollection]
+      def load_calls
+        filter(&:load?)
+      end
+    end
+  end
+end

data/lib/rubyzen/collections/rescues_collection.rb

@@ -0,0 +1,19 @@
+module Rubyzen
+  module Collections
+    # Collection of rescue declarations found in methods or classes.
+    #
+    # @example Checking for StandardError rescues
+    #   project.files.classes.all_methods.rescues.with_exception_type('StandardError')
+    class RescuesCollection < BaseCollection
+      # Filters rescues that handle the given exception class.
+      #
+      # @param exception_class [String] the exception class name to match
+      # @return [RescuesCollection]
+      def with_exception_type(exception_class)
+        filter do |rescue_declaration|
+          rescue_declaration.exception_types.include?(exception_class)
+        end
+      end
+    end
+  end
+end

data/lib/rubyzen/declarations/attribute_declaration.rb

@@ -0,0 +1,62 @@
+module Rubyzen
+  module Declarations
+    # Represents an +attr_reader+, +attr_writer+, or +attr_accessor+ declaration.
+    #
+    # @example
+    #   attr = klass.attributes.first
+    #   attr.name      #=> "attr_reader"
+    #   attr.symbols   #=> ["name", "email"]
+    #   attr.reader?   #=> true
+    #   attr.private?  #=> false
+    #
+    class AttributeDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::ClassNameProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::VisibilityProvider
+
+      # @return [RuboCop::AST::Node]
+      attr_reader :node
+
+      # @return [ClassDeclaration, ModuleDeclaration]
+      attr_reader :parent_class
+      alias :parent :parent_class
+
+      # @param node [RuboCop::AST::Node] the AST node
+      # @param parent_class [ClassDeclaration, ModuleDeclaration] the parent declaration
+      def initialize(node, parent_class)
+        @node = node
+        @parent_class = parent_class
+      end
+
+      # Returns the attribute type name.
+      #
+      # @return [String] one of +"attr_reader"+, +"attr_writer"+, +"attr_accessor"+
+      def name
+        node.method_name.to_s
+      end
+
+      # Returns the declared symbol names.
+      #
+      # @return [Array<String>] e.g. +["name", "email"]+
+      def symbols
+        node.arguments.map { |arg| arg.value.to_s if arg.type == :sym }.compact
+      end
+
+      # @return [Boolean] true for +attr_reader+ and +attr_accessor+
+      def reader?
+        %w[attr_reader attr_accessor].include?(name)
+      end
+
+      # @return [Boolean] true for +attr_writer+ and +attr_accessor+
+      def writer?
+        %w[attr_writer attr_accessor].include?(name)
+      end
+
+      # @return [Boolean] true only for +attr_accessor+
+      def accessor?
+        name == 'attr_accessor'
+      end
+    end
+  end
+end

data/lib/rubyzen/declarations/block_declaration.rb

@@ -0,0 +1,49 @@
+module Rubyzen
+  module Declarations
+    # Represents a Ruby block (+do...end+ or +{ }+).
+    #
+    # @example
+    #   block = method.blocks.first
+    #   block.method_name   #=> "each"
+    #   block.call_sites    #=> CallSiteCollection
+    #   block.lines_of_code #=> 5
+    #
+    class BlockDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::ClassNameProvider
+      include Rubyzen::Providers::LinesOfCodeProvider
+      include Rubyzen::Providers::RescuesProvider
+      include Rubyzen::Providers::RaisesProvider
+      include Rubyzen::Providers::SourceCodeProvider
+      include Rubyzen::Providers::CallSiteProvider
+
+      # @return [RuboCop::AST::Node]
+      attr_reader :node
+
+      # @return [MethodDeclaration, FileDeclaration]
+      attr_reader :parent
+
+      # @param node [RuboCop::AST::Node] the AST node
+      # @param parent [MethodDeclaration, FileDeclaration] the parent declaration
+      def initialize(node, parent)
+        @node = node
+        @parent = parent
+      end
+
+      # Returns the method name the block is passed to. Alias for {#method_name}.
+      #
+      # @return [String]
+      def name
+        method_name
+      end
+
+      # Returns the method name the block is passed to.
+      #
+      # @return [String] e.g. +"each"+, +"map"+, +"let"+
+      def method_name
+        node.method_name.to_s
+      end
+    end
+  end
+end

data/lib/rubyzen/declarations/call_site_declaration.rb

@@ -0,0 +1,98 @@
+module Rubyzen
+  module Declarations
+    # Represents a method call site (a +send+ node in the AST).
+    #
+    # @example
+    #   call_site = method.call_sites.first
+    #   call_site.method_name   #=> "find"
+    #   call_site.receiver      #=> "User"
+    #   call_site.keyword_args  #=> [:id, :name]
+    #
+    class CallSiteDeclaration
+      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, FileDeclaration]
+      attr_reader :parent
+
+      # @param node [RuboCop::AST::Node] the AST node
+      # @param parent [MethodDeclaration, BlockDeclaration, FileDeclaration] the parent declaration
+      def initialize(node, parent)
+        @node = node
+        @parent = parent
+      end
+
+      # Returns the called method name. Alias for {#method_name}.
+      #
+      # @return [String]
+      def name
+        method_name
+      end
+
+      # Returns the constant name of the receiver, if any.
+      #
+      # @return [String, nil] e.g. +"User"+ for +User.find(1)+, +nil+ for +save+
+      def receiver
+        node.receiver&.type == :const ? node.receiver.const_name : nil
+      end
+
+      # Returns the called method name.
+      #
+      # @return [String]
+      def method_name
+        node.method_name.to_s
+      end
+
+      # Returns the keyword argument keys passed in the call.
+      #
+      # @return [Array<Symbol>] e.g. +[:level, :details]+
+      def keyword_args
+        node.arguments.flat_map do |arg|
+          next [] unless arg.hash_type?
+
+          arg.pairs.filter_map do |pair|
+            pair.key.value if pair.key.type == :sym
+          end
+        end.uniq
+      end
+
+      # Returns a hash mapping keyword argument keys to their literal values.
+      #
+      # @return [Hash{Symbol => Object}] values are +nil+ for non-literal expressions
+      def keyword_arg_value_pairs
+        result = {}
+        node.arguments.each do |arg|
+          next unless arg.hash_type?
+
+          arg.pairs.each do |pair|
+            next unless pair.key.type == :sym
+
+            value_node = pair.value
+            result[pair.key.value] = value_node.respond_to?(:value) ? value_node.value : nil
+          end
+        end
+        result
+      end
+
+      # Returns positional symbol arguments.
+      #
+      # @return [Array<Symbol>] e.g. +[:name, :email]+
+      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
+
+    end
+  end
+end

data/lib/rubyzen/declarations/class_declaration.rb

@@ -0,0 +1,168 @@
+module Rubyzen
+  module Declarations
+    # Represents a Ruby class definition. Provides access to methods, attributes,
+    # macros, and other class-level constructs.
+    #
+    # @example
+    #   klass = file.classes.first
+    #   klass.name                #=> "Admin::UsersController"
+    #   klass.superclass_name     #=> "ApplicationController"
+    #   klass.instance_methods    #=> MethodsCollection
+    #
+    class ClassDeclaration
+      include Rubyzen::Providers::IfStatementsProvider
+      include Rubyzen::Providers::BlocksProvider
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::LinesOfCodeProvider
+      include Rubyzen::Providers::ClassNameProvider
+      include Rubyzen::Providers::ConstantsProvider
+      include Rubyzen::Providers::AttributesProvider
+      include Rubyzen::Providers::MacrosProvider
+      include Rubyzen::Providers::RescuesProvider
+      include Rubyzen::Providers::RaisesProvider
+
+      # @return [RuboCop::AST::Node] the class AST node
+      attr_reader :node
+
+      # @return [FileDeclaration] the file this class belongs to
+      attr_reader :file_declaration
+
+      # @param node [RuboCop::AST::Node]
+      # @param file_declaration [FileDeclaration]
+      def initialize(node, file_declaration)
+        @node = node
+        @file_declaration = file_declaration
+      end
+
+      # Returns the fully-qualified class name including parent modules.
+      #
+      # @return [String] e.g. +"Admin::UsersController"+
+      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 class name without module prefixes.
+      #
+      # @return [String] e.g. +"UsersController"+
+      def name_without_modules
+        node.identifier&.const_name
+      end
+
+      # Returns the superclass name, if any.
+      #
+      # @return [String, nil] e.g. +"ApplicationController"+
+      def superclass_name
+        super_node = node.children[1]
+        return nil unless super_node&.type == :const
+
+        super_node.const_name
+      end
+
+      # Checks whether the superclass name starts with the given prefix.
+      #
+      # @param prefix [String]
+      # @return [Boolean]
+      def superclass_prefix?(prefix)
+        superclass_name&.start_with?(prefix)
+      end
+
+      # Returns instance methods defined directly in this class.
+      #
+      # @return [Collections::MethodsCollection]
+      def instance_methods
+        Collections::MethodsCollection.new(
+          instance_method_nodes.map do |def_node|
+            MethodDeclaration.new(def_node, self)
+          end
+        )
+      end
+
+      # Returns class methods (both +self.method+ and +class << self+ styles).
+      #
+      # @return [Collections::MethodsCollection]
+      def class_methods
+        Collections::MethodsCollection.new(
+          class_method_nodes.map do |method_node|
+            MethodDeclaration.new(method_node, self)
+          end
+        )
+      end
+
+      # Returns unique method names called anywhere in this class.
+      #
+      # @return [Array<String>]
+      def called_method_names
+        node.each_descendant(:send).map { |send_node| send_node.method_name.to_s }.uniq
+      end
+
+      # Returns the top-level module name from the enclosing file.
+      #
+      # @return [String, nil]
+      def top_level_module
+        file_declaration.top_level_module_name
+      end
+
+      private
+
+      def class_body_node
+        node.children[2]
+      end
+
+      def class_body_children
+        body = class_body_node
+        return [] unless body
+
+        body.type == :begin ? body.child_nodes : [body]
+      end
+
+      def instance_method_nodes
+        class_body_children.select { |child| child.type == :def }
+      end
+
+      def class_defs_nodes
+        class_body_children.select do |child|
+          child.type == :defs && child.children[0]&.type == :self
+        end
+      end
+
+      def class_method_nodes
+        class_defs_nodes + class_sclass_def_nodes
+      end
+
+      def class_sclass_def_nodes
+        class_body_children
+          .select { |child| singleton_class_node?(child) }
+          .flat_map do |child|
+          body_children(child.children[1]).select do |body_child|
+            method_node?(body_child)
+          end
+        end
+      end
+
+      def singleton_class_node?(child)
+        child.type == :sclass && child.children[0]&.type == :self
+      end
+
+      def body_children(body)
+        return [] unless body
+
+        body.type == :begin ? body.child_nodes : [body]
+      end
+
+      def method_node?(child)
+        %i[def defs].include?(child.type)
+      end
+    end
+  end
+end