rubyzen-lint 0.1.0

data/lib/rubyzen/declarations/require_declaration.rb

@@ -0,0 +1,61 @@
+module Rubyzen
+  module Declarations
+    # Represents a +require+, +require_relative+, or +load+ statement.
+    #
+    # @example
+    #   req = file.requires.first
+    #   req.required_path     #=> "json"
+    #   req.require?          #=> true
+    #   req.require_relative? #=> false
+    #
+    class RequireDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::LineNumberProvider
+
+      # @return [RuboCop::AST::Node]
+      attr_reader :node
+
+      # @return [FileDeclaration]
+      attr_reader :parent_file
+      alias :parent :parent_file
+
+      # @param node [RuboCop::AST::Node] the AST node
+      # @param parent_file [FileDeclaration] the parent file declaration
+      def initialize(node, parent_file)
+        @node = node
+        @parent_file = parent_file
+      end
+
+      # Returns the statement type.
+      #
+      # @return [String] one of +"require"+, +"require_relative"+, +"load"+
+      def name
+        node.method_name.to_s
+      end
+
+      # Returns the required path string.
+      #
+      # @return [String, nil]
+      def required_path
+        first_arg = node.arguments.first
+        return nil unless first_arg&.type == :str
+        first_arg.value
+      end
+
+      # @return [Boolean]
+      def require?
+        name == 'require'
+      end
+
+      # @return [Boolean]
+      def require_relative?
+        name == 'require_relative'
+      end
+
+      # @return [Boolean]
+      def load?
+        name == 'load'
+      end
+    end
+  end
+end

data/lib/rubyzen/declarations/rescue_declaration.rb

@@ -0,0 +1,54 @@
+module Rubyzen
+  module Declarations
+    # Represents a +rescue+ clause within a method or block.
+    #
+    # @example
+    #   rescue_decl = method.rescues.first
+    #   rescue_decl.exception_types #=> ["ArgumentError", "TypeError"]
+    #
+    class RescueDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::ClassNameProvider
+
+      # @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 rescued exception class names.
+      # Defaults to +["StandardError"]+ for bare +rescue+.
+      #
+      # @return [Array<String>]
+      def exception_types
+        extract_exception_types
+      end
+
+      private
+
+      def extract_exception_types
+        exception_array_node = node.children[0]
+
+        return ['StandardError'] if exception_array_node.nil?
+
+        exception_array_node.children.map do |const_node|
+          extract_const_name(const_node)
+        end.compact
+      end
+
+      def extract_const_name(node)
+        return nil unless node&.type == :const
+
+        node.const_name
+      end
+    end
+  end
+end

data/lib/rubyzen/lint.rb

@@ -0,0 +1 @@
+require_relative '../rubyzen'

data/lib/rubyzen/matchers/matcher_helpers.rb

@@ -0,0 +1,176 @@
+module Rubyzen
+  module Matchers
+    # Shared helper methods used by Rubyzen's custom RSpec matchers.
+    #
+    # Provides utilities for normalizing exception lists, extracting item
+    # details, matching items against allowlist/baseline entries, and
+    # formatting failure messages.
+    module MatcherHelpers
+      # Normalizes a list of exception entries into unique, non-blank strings.
+      #
+      # @param entries [Array<String>, String, nil] raw exception entries
+      # @return [Array<String>] deduplicated, stripped, non-empty strings
+      def normalize_exception_entries(entries)
+        Array(entries).flatten.compact.map(&:to_s).map(&:strip).reject(&:empty?).uniq
+      end
+
+      # Extracts identifying details from a declaration item.
+      #
+      # @param item [Object] a declaration object (e.g., FileDeclaration, ClassDeclaration)
+      # @return [Hash{Symbol => String, nil}] hash with :name, :class_name, :file_path, :line
+      def item_details(item)
+        {
+          name: item.respond_to?(:name) ? item.name : nil,
+          class_name: item.respond_to?(:class_name) ? item.class_name : nil,
+          file_path: item.respond_to?(:file_path) ? item.file_path : 'Unknown file',
+          line: item.respond_to?(:line) ? item.line : nil
+        }
+      end
+
+      # Returns a list of unique identifier strings for an item, used for matching.
+      #
+      # @param item [Object] a declaration object
+      # @return [Array<String>] identifiers such as name, class name, file path, and file:line
+      def item_identifiers(item)
+        details = item_details(item)
+        identifiers = [details[:name], details[:class_name], details[:file_path]]
+
+        if details[:line]
+          identifiers << "#{details[:file_path]}:#{details[:line]}"
+        end
+
+        identifiers.compact.uniq
+      end
+
+      # Checks whether a given exception entry string matches an item.
+      #
+      # @param entry [String] an allowlist or baseline entry
+      # @param item [Object] a declaration object
+      # @return [Boolean] true if the entry matches the item by name, class, or path
+      def exception_entry_matches_item?(entry, item)
+        normalized_entry = entry.to_s.strip
+        return false if normalized_entry.empty?
+
+        details = item_details(item)
+        return true if item_identifiers(item).include?(normalized_entry)
+
+        file_path = details[:file_path]
+        file_path && (file_path.end_with?(normalized_entry) || file_path.end_with?("/#{normalized_entry}"))
+      end
+
+      # Classifies items into violations, baseline matches, allowlist matches,
+      # and detects stale entries in either list.
+      #
+      # @param subject_collection [Array, Object] items to classify
+      # @param allowlist [Array<String>, nil] allowed exception entries
+      # @param baseline [Array<String>, nil] baseline exception entries
+      # @return [Hash{Symbol => Array<String>}] keys: :violations, :baseline, :allowlist,
+      #   :stale_baseline, :stale_allowlist
+      def classify_items(subject_collection, allowlist: nil, baseline: nil)
+        items = Array(subject_collection).compact
+        normalized_allowlist = normalize_exception_entries(allowlist)
+        normalized_baseline = normalize_exception_entries(baseline)
+        matched_baseline_entries = []
+        matched_allowlist_entries = []
+
+        grouped_items = items.group_by do |item|
+          matching_baseline_entry = normalized_baseline.find do |entry|
+            exception_entry_matches_item?(entry, item)
+          end
+
+          if matching_baseline_entry
+            matched_baseline_entries << matching_baseline_entry
+            :baseline
+          else
+            matching_allowlist_entry = normalized_allowlist.find do |entry|
+              exception_entry_matches_item?(entry, item)
+            end
+
+            if matching_allowlist_entry
+              matched_allowlist_entries << matching_allowlist_entry
+              :allowlist
+            else
+              :violations
+            end
+          end
+        end
+
+        classifications = {
+          baseline: Array(grouped_items[:baseline]).map { |item| element_name(item) },
+          allowlist: Array(grouped_items[:allowlist]).map { |item| element_name(item) },
+          violations: Array(grouped_items[:violations]).map { |item| element_name(item) }
+        }
+
+        classifications.merge(
+          stale_baseline: normalized_baseline - matched_baseline_entries.uniq,
+          stale_allowlist: normalized_allowlist - matched_allowlist_entries.uniq
+        )
+      end
+
+      # Formats a human-readable description of an item for failure messages.
+      #
+      # @param item [Object] a declaration object
+      # @return [String] formatted multi-line description
+      def element_name(item)
+        details = item_details(item)
+        location = [details[:file_path], details[:line]].compact.join(':')
+
+        case
+        when details[:name] && details[:class_name]
+          "  - element: #{details[:name]}\n  - class: #{details[:class_name]}\n  - file: #{location}"
+        when details[:name]
+          "  - element: #{details[:name]}\n  - file: #{location}"
+        when details[:class_name]
+          "  - class: #{details[:class_name]}\n  - file: #{location}"
+        else
+          "  - unknown element in #{location}"
+        end
+      end
+
+      # Builds a formatted string of violations and stale entries for failure output.
+      #
+      # @return [String, nil] formatted sections or nil if no classified items
+      def formatted_matcher_groups
+        return unless defined?(@classified_items) && @classified_items
+
+        sections = []
+
+        if @classified_items[:violations].any?
+          sections << "Violations:\n#{@classified_items[:violations].join("\n")}"
+        end
+
+        if @classified_items[:stale_baseline].any?
+          stale_entries = @classified_items[:stale_baseline].map { |entry| "  - #{entry}" }
+          sections << "Stale baseline entries:\n#{stale_entries.join("\n")}"
+        end
+
+        if @classified_items[:stale_allowlist].any?
+          stale_entries = @classified_items[:stale_allowlist].map { |entry| "  - #{entry}" }
+          sections << "Stale allowlist entries:\n#{stale_entries.join("\n")}"
+        end
+
+        sections.join("\n")
+      end
+
+      def self.included(base)
+        base.define_method(:message_for_failure) do |base_message|
+          return @failure_message if @failure_message
+
+          details = formatted_matcher_groups
+
+          if @custom_message
+            if details && !details.empty?
+              "#{@custom_message}\n#{details}"
+            else
+              @custom_message
+            end
+          elsif details && !details.empty?
+            "#{base_message}\n#{details}"
+          else
+            base_message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubyzen/matchers/zen_empty_matcher.rb

@@ -0,0 +1,54 @@
+# Custom RSpec matcher that asserts a Rubyzen collection is empty.
+#
+# Used in architectural lint rules to verify that no items match
+# a forbidden pattern (e.g., no controllers call +.where+ directly).
+#
+# @example Ensure no controllers use .where
+#   expect(controllers.all_methods.call_sites.with_name('where')).to zen_empty
+#
+# @example With a custom failure message
+#   expect(violations).to zen_empty("Controllers should not call .where directly")
+RSpec::Matchers.define :zen_empty do |custom_message=nil, allowlist: nil, baseline: nil|
+  include Rubyzen::Matchers::MatcherHelpers
+
+  match do |subject_collection|
+    options = custom_message.is_a?(Hash) ? custom_message : {}
+    resolved_allowlist = allowlist || options[:allowlist] || options['allowlist']
+    resolved_baseline = baseline || options[:baseline] || options['baseline']
+    @custom_message = options[:message] || options['message'] || (custom_message unless custom_message.is_a?(Hash))
+
+    @classified_items = classify_items(
+      subject_collection,
+      allowlist: resolved_allowlist,
+      baseline: resolved_baseline
+    )
+    @offenders = @classified_items[:violations]
+    stale_exception_groups = []
+    stale_exception_groups << 'baseline entries' if @classified_items[:stale_baseline].any?
+    stale_exception_groups << 'allowlist entries' if @classified_items[:stale_allowlist].any?
+
+    @failure_reason = if @classified_items[:violations].any? && stale_exception_groups.any?
+                        "Expected to be empty, but found live violations and stale #{stale_exception_groups.join(' and ')}."
+                      elsif @classified_items[:violations].any?
+                        if resolved_baseline || resolved_allowlist
+                          'Expected to be empty, but found live violations.'
+                        else
+                          'Expected to be empty, but had elements.'
+                        end
+                      elsif stale_exception_groups.any?
+                        "Expected to be empty, but found stale #{stale_exception_groups.join(' and ')}."
+                      end
+
+    @classified_items[:violations].empty? &&
+      @classified_items[:stale_baseline].empty? &&
+      @classified_items[:stale_allowlist].empty?
+  end
+
+  failure_message do |_|
+    message_for_failure(@failure_reason || 'Expected to be empty, but had elements.')
+  end
+
+  failure_message_when_negated do |_|
+    message_for_failure('Expected not to be empty, but had no elements.')
+  end
+end

data/lib/rubyzen/matchers/zen_false_matcher.rb

@@ -0,0 +1,63 @@
+# Custom RSpec matcher that asserts a block returns false for every item in a collection.
+#
+# Supports +allowlist:+ and +baseline:+ for gradual adoption, matching items
+# where the block returns true against exception lists.
+#
+# @example Ensure no methods have more than 5 parameters
+#   expect(methods).to zen_false { |m| m.parameters.size > 5 }
+#
+# @example With a custom failure message
+#   expect(controllers.all_methods.call_sites).to zen_false("Controllers must not call .where directly") { |cs| cs.name == 'where' }
+#
+# @example With a baseline for gradual adoption
+#   expect(classes).to zen_false(baseline: ['LegacyModel']) { |k| k.lines_of_code > 200 }
+RSpec::Matchers.define :zen_false do |custom_message=nil, allowlist: nil, baseline: nil|
+  include Rubyzen::Matchers::MatcherHelpers
+
+  match do |subject_collection|
+    options = custom_message.is_a?(Hash) ? custom_message : {}
+    resolved_allowlist = allowlist || options[:allowlist] || options['allowlist']
+    resolved_baseline = baseline || options[:baseline] || options['baseline']
+    @custom_message = options[:message] || options['message'] || (custom_message unless custom_message.is_a?(Hash))
+    @offenders = []
+
+    if block_arg != nil
+      items = Array(subject_collection)
+
+      failing_items = items.filter { |item| block_arg.call(item) }
+      @classified_items = classify_items(
+        failing_items,
+        allowlist: resolved_allowlist,
+        baseline: resolved_baseline
+      )
+      @offenders = @classified_items[:violations]
+
+      stale_exception_groups = []
+      stale_baseline = @classified_items[:stale_baseline]
+      stale_allowlist = @classified_items[:stale_allowlist]
+      stale_exception_groups << 'baseline entries' if stale_baseline.any?
+      stale_exception_groups << 'allowlist entries' if stale_allowlist.any?
+
+      @failure_reason = if @offenders.any? && stale_exception_groups.any?
+                          "Expected to return false for all elements, but found live violations and stale #{stale_exception_groups.join(' and ')}."
+                        elsif @offenders.any?
+                          "Expected to return false for all elements."
+                        elsif stale_exception_groups.any?
+                          "Expected to return false for all elements, but found stale #{stale_exception_groups.join(' and ')}."
+                        end
+
+      @offenders.empty? && stale_baseline.empty? && stale_allowlist.empty?
+    else
+      @failure_reason = "Expected a block, but got nil."
+      false
+    end
+  end
+
+  failure_message do |_|
+    message_for_failure(@failure_reason || "Expected to return false for all elements.")
+  end
+
+  failure_message_when_negated do |_|
+    message_for_failure("Expected to return true for at least one element, but all elements returned false.")
+  end
+end

data/lib/rubyzen/matchers/zen_true_matcher.rb

@@ -0,0 +1,57 @@
+# Custom RSpec matcher that asserts a block returns true for every item in a collection.
+#
+# @example Ensure all methods have parameters
+#   expect(methods).to zen_true { |m| m.parameters? }
+#
+# @example With a custom failure message
+#   expect(services).to zen_true("All services must inherit from BaseService") { |s| s.superclass_name == 'BaseService' }
+RSpec::Matchers.define :zen_true do |custom_message=nil, allowlist: nil, baseline: nil|
+  include Rubyzen::Matchers::MatcherHelpers
+
+  match do |subject_collection|
+    options = custom_message.is_a?(Hash) ? custom_message : {}
+    resolved_allowlist = allowlist || options[:allowlist] || options['allowlist']
+    resolved_baseline = baseline || options[:baseline] || options['baseline']
+    @custom_message = options[:message] || options['message'] || (custom_message unless custom_message.is_a?(Hash))
+    @offenders = []
+
+    if block_arg != nil
+      items = Array(subject_collection) # to handle one or multiple subjects
+
+      failing_items = items.filter { |item| !block_arg.call(item) }
+      @classified_items = classify_items(
+        failing_items,
+        allowlist: resolved_allowlist,
+        baseline: resolved_baseline
+      )
+      @offenders = @classified_items[:violations]
+
+      stale_exception_groups = []
+      stale_baseline = @classified_items[:stale_baseline]
+      stale_allowlist = @classified_items[:stale_allowlist]
+      stale_exception_groups << 'baseline entries' if stale_baseline.any?
+      stale_exception_groups << 'allowlist entries' if stale_allowlist.any?
+
+      @failure_reason = if @offenders.any? && stale_exception_groups.any?
+                          "Expected to return true for all elements, but found live violations and stale #{stale_exception_groups.join(' and ')}."
+                        elsif @offenders.any?
+                          "Expected to return true for all elements."
+                        elsif stale_exception_groups.any?
+                          "Expected to return true for all elements, but found stale #{stale_exception_groups.join(' and ')}."
+                        end
+
+      @offenders.empty? && stale_baseline.empty? && stale_allowlist.empty?
+    else
+      @failure_reason = "Expected a block, but got nil."
+      false
+    end
+  end
+
+  failure_message do |_|
+    message_for_failure(@failure_reason || "Expected to return true for all elements.")
+  end
+
+  failure_message_when_negated do |_|
+    message_for_failure("Expected to return false for at least one element, but all elements returned true.")
+  end
+end

data/lib/rubyzen/parsers/a_s_t_parser.rb

@@ -0,0 +1,33 @@
+require 'rubocop-ast'
+
+module Rubyzen
+  module Parsers
+    # Singleton parser that converts Ruby source files into Rubyzen declarations
+    # using RuboCop's AST processing. Results are cached via {Cache::ParseCache}.
+    class ASTParser
+      # Returns the singleton instance of the parser.
+      #
+      # @return [ASTParser]
+      def self.instance
+        @instance ||= new
+      end
+
+      def initialize
+        @cache = Rubyzen::Cache::ParseCache.new
+      end
+
+      # Parses a Ruby source file and returns its declaration, using the cache.
+      #
+      # @param file_path [String] absolute path to the Ruby file
+      # @return [Declarations::FileDeclaration, nil] the parsed file declaration, or nil if unparseable
+      def parse_file(file_path)
+        @cache.fetch_or_parse(file_path) do
+          source = File.read(file_path)
+          processed_source = RuboCop::AST::ProcessedSource.new(source, RUBY_VERSION.to_f, file_path)
+          next nil unless processed_source.ast
+          Rubyzen::Declarations::FileDeclaration.new(file_path, processed_source.ast)
+        end
+      end
+    end
+  end
+end

data/lib/rubyzen/project.rb

@@ -0,0 +1,69 @@
+module Rubyzen
+  # Main entry point for analyzing a Ruby project. Parses all +.rb+ files
+  # in the given paths and provides access to files, classes, and modules.
+  #
+  # @example Analyzing specific directories
+  #   project = Rubyzen::Project.new(["app/models", "app/controllers"])
+  #   project.files.with_paths("controllers/").classes
+  #
+  # @example Using auto-discovery
+  #   project = Rubyzen::Project.new  # scans app/, lib/, src/, spec/
+  #   project.classes.with_name("UsersController")
+  #
+  class Project
+    # @param paths [String, Array<String>, nil] directories or file paths to analyze.
+    #   Falls back to {Configuration#project_paths} (auto-discovery) if nil.
+    def initialize(paths = nil)
+      paths ||= Rubyzen.configuration.project_paths
+      @root_paths = Array(paths).map { |p| File.expand_path(p) }
+
+      @root_paths.each do |path|
+        unless File.exist?(path)
+          raise Rubyzen::Error, "Path does not exist: #{path}"
+        end
+      end
+
+      @file_paths = @root_paths.flat_map do |path|
+        if File.directory?(path)
+          Dir[File.join(path, '**', '*.rb')]
+        else
+          [path]
+        end
+      end.uniq
+
+      @parser = Rubyzen::Parsers::ASTParser.instance
+    end
+
+    # Returns all parsed files as a filterable collection.
+    #
+    # @return [Collections::FileCollection]
+    def files
+      all_files = file_declarations
+      Collections::FileCollection.new(all_files)
+    end
+
+    # Returns all classes found across all parsed files.
+    #
+    # @return [Collections::ClassesCollection]
+    def classes
+      all_classes = file_declarations.flat_map(&:classes)
+      Collections::ClassesCollection.new(all_classes)
+    end
+
+    # Returns all modules found across all parsed files.
+    #
+    # @return [Collections::ModulesCollection]
+    def modules
+      all_modules = file_declarations.flat_map(&:modules)
+      Collections::ModulesCollection.new(all_modules)
+    end
+
+    private
+
+    def file_declarations
+      @file_declarations ||= @file_paths.map do |file_path|
+        @parser.parse_file(file_path)
+      end.compact
+    end
+  end
+end

data/lib/rubyzen/providers/attributes_provider.rb

@@ -0,0 +1,19 @@
+module Rubyzen
+  module Providers
+    # Provides access to attr_reader, attr_writer, and attr_accessor declarations.
+    module AttributesProvider
+      # @return [Rubyzen::Collections::AttributesCollection] collection of attribute declarations
+      def attributes
+        attribute_nodes = node.each_descendant(:send).select do |send_node|
+          %w[attr_reader attr_writer attr_accessor].include?(send_node.method_name.to_s)
+        end
+
+        attribute_declarations = attribute_nodes.map do |attr_node|
+          Rubyzen::Declarations::AttributeDeclaration.new(attr_node, self)
+        end
+
+        Rubyzen::Collections::AttributesCollection.new(attribute_declarations)
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/blocks_provider.rb

@@ -0,0 +1,15 @@
+module Rubyzen
+  module Providers
+    # Provides access to block expressions (do..end / {..}) within a declaration.
+    module BlocksProvider
+      # @return [Rubyzen::Collections::BlocksCollection] collection of block declarations
+      def blocks
+        Collections::BlocksCollection.new(
+          node.each_descendant(:block).map do |block_node|
+            Declarations::BlockDeclaration.new(block_node, self)
+          end
+        )
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/call_site_provider.rb

@@ -0,0 +1,15 @@
+module Rubyzen
+  module Providers
+    # Provides access to method call sites within a declaration.
+    module CallSiteProvider
+      # @return [Rubyzen::Collections::CallSiteCollection] collection of call site declarations
+      def call_sites
+        Collections::CallSiteCollection.new(
+          node.each_descendant(:send).map do |send_node|
+            Declarations::CallSiteDeclaration.new(send_node, self)
+          end
+        )
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/class_name_provider.rb

@@ -0,0 +1,36 @@
+module Rubyzen
+  module Providers
+    # Provides access to the enclosing class name by traversing parent declarations.
+    module ClassNameProvider
+      # @return [String, nil] the name of the enclosing class, or nil if not within a class
+      def class_name
+        class_name_recursive(self)
+      end
+
+      private
+
+      def class_name_recursive(declaration)
+        return if declaration.nil?
+        return nil if declaration.is_a?(Rubyzen::Declarations::FileDeclaration)
+        return declaration.name if declaration.is_a?(Rubyzen::Declarations::ClassDeclaration)
+
+        if declaration.is_a?(Rubyzen::Declarations::ModuleDeclaration)
+          return module_class_name(declaration)
+        end
+
+        class_name_recursive(parent_declaration(declaration))
+      end
+
+      def module_class_name(declaration)
+        parent_class_name = class_name_recursive(parent_declaration(declaration))
+        parent_class_name || declaration.name
+      end
+
+      def parent_declaration(declaration)
+        return unless declaration.respond_to?(:parent)
+
+        declaration.parent
+      end
+    end
+  end
+end